openapi: 3.1.0
info:
title: Reddit Data API
description: >-
The Reddit Data API provides programmatic access to Reddit content
including subreddits, posts, comments, user profiles, and voting data.
Developers can use the API to read and submit content, manage
subreddits, search across the platform, and interact with Reddit
communities. All requests require OAuth 2.0 authentication via
oauth.reddit.com, with rate limits of 60 requests per minute for
authenticated clients.
version: '1.0'
contact:
name: Reddit Developer Support
url: https://support.reddithelp.com/hc/en-us/articles/16160319875092-Reddit-Data-API-Wiki
termsOfService: https://www.redditinc.com/policies/data-api-terms
externalDocs:
description: Reddit API Documentation
url: https://www.reddit.com/dev/api
servers:
- url: https://oauth.reddit.com
description: OAuth API Server
tags:
- name: Account
description: >-
Endpoints related to the authenticated user account, including
identity, preferences, karma, trophies, and friend management.
- name: Flair
description: >-
Endpoints for managing user and link flair within subreddits,
including flair templates, assignments, and configuration.
- name: Links & Comments
description: >-
Endpoints for interacting with submissions (links) and comments,
including voting, saving, hiding, reporting, and submitting content.
- name: Listings
description: >-
Endpoints for retrieving sorted listings of content from subreddits,
including hot, new, rising, top, and controversial posts.
- name: Messages
description: >-
Endpoints for managing private messages, including inbox, sent,
unread messages, composing, and message actions.
- name: Moderation
description: >-
Endpoints for subreddit moderation tasks, including approving and
removing content, managing bans, moderation logs, and modqueue.
- name: Search
description: >-
Endpoints for searching Reddit content including submissions,
subreddits, and users across the platform.
- name: Subreddits
description: >-
Endpoints for managing and retrieving information about subreddits,
including subscription, creation, rules, and settings.
- name: Users
description: >-
Endpoints for retrieving information about Reddit users, including
profiles, post history, comment history, and trophies.
- name: Wiki
description: >-
Endpoints for managing subreddit wikis, including reading and
editing wiki pages, revision history, and permissions.
security:
- oauth2: []
paths:
/api/v1/me:
get:
operationId: getMe
summary: Get Current User Identity
description: >-
Returns the identity of the currently authenticated user, including
username, karma, account age, and preferences.
tags:
- Account
responses:
'200':
description: Successful response with user identity
content:
application/json:
schema:
$ref: '#/components/schemas/Account'
'401':
description: Authentication required
/api/v1/me/prefs:
get:
operationId: getMyPrefs
summary: Get User Preferences
description: >-
Returns the preference settings of the currently authenticated user.
tags:
- Account
responses:
'200':
description: Successful response with user preferences
content:
application/json:
schema:
type: object
'401':
description: Authentication required
patch:
operationId: updateMyPrefs
summary: Update User Preferences
description: >-
Updates the preference settings of the currently authenticated user.
tags:
- Account
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
'200':
description: Preferences updated successfully
content:
application/json:
schema:
type: object
'401':
description: Authentication required
/api/v1/me/karma:
get:
operationId: getMyKarma
summary: Get Karma Breakdown by Subreddit
description: >-
Returns a breakdown of the current user's karma by subreddit,
including link karma and comment karma for each subreddit.
tags:
- Account
responses:
'200':
description: Successful response with karma breakdown
content:
application/json:
schema:
type: object
properties:
kind:
type: string
data:
type: array
items:
$ref: '#/components/schemas/KarmaBreakdown'
'401':
description: Authentication required
/api/v1/me/trophies:
get:
operationId: getMyTrophies
summary: Get Current User Trophies
description: >-
Returns a list of trophies for the currently authenticated user.
tags:
- Account
responses:
'200':
description: Successful response with trophies
content:
application/json:
schema:
type: object
'401':
description: Authentication required
/api/v1/me/friends:
get:
operationId: getMyFriends
summary: Get Friends List
description: >-
Returns a list of the current user's friends.
tags:
- Account
responses:
'200':
description: Successful response with friends list
content:
application/json:
schema:
type: object
'401':
description: Authentication required
/api/v1/me/blocked:
get:
operationId: getMyBlocked
summary: Get Blocked Users List
description: >-
Returns a list of users blocked by the currently authenticated user.
tags:
- Account
responses:
'200':
description: Successful response with blocked users
content:
application/json:
schema:
type: object
'401':
description: Authentication required
/r/{subreddit}/hot:
get:
operationId: getHotListings
summary: Get Hot Listings
description: >-
Returns a listing of hot posts from the specified subreddit. Results
are sorted by Reddit's hot ranking algorithm.
tags:
- Listings
parameters:
- $ref: '#/components/parameters/subreddit'
- $ref: '#/components/parameters/after'
- $ref: '#/components/parameters/before'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/count'
- name: g
in: query
description: >-
Geolocation filter for location-specific hot listings.
schema:
type: string
enum:
- GLOBAL
- US
- AR
- AU
- BG
- CA
- CL
- CO
- HR
- CZ
- FI
- FR
- DE
- GR
- HU
- IS
- IN
- IE
- IT
- JP
- MY
- MX
- NZ
- PH
- PL
- PT
- PR
- RO
- RS
- SG
- ES
- SE
- TW
- TH
- TR
- GB
- US_WA
- US_DE
- US_DC
- US_WI
- US_WV
- US_HI
- US_FL
- US_NH
- US_NJ
- US_NM
- US_TX
- US_LA
- US_NC
- US_ND
- US_NE
- US_TN
- US_NY
- US_PA
- US_CA
- US_NV
- US_VA
- US_CO
- US_AK
- US_AL
- US_AR
- US_VT
- US_IL
- US_GA
- US_IN
- US_IA
- US_OK
- US_AZ
- US_ID
- US_CT
- US_ME
- US_MD
- US_MA
- US_OH
- US_UT
- US_MO
- US_MN
- US_MI
- US_RI
- US_KS
- US_MT
- US_MS
- US_SC
- US_KY
- US_OR
- US_SD
responses:
'200':
description: Listing of hot posts
content:
application/json:
schema:
$ref: '#/components/schemas/Listing'
/r/{subreddit}/new:
get:
operationId: getNewListings
summary: Get New Listings
description: >-
Returns a listing of new posts from the specified subreddit, sorted
by submission time with newest first.
tags:
- Listings
parameters:
- $ref: '#/components/parameters/subreddit'
- $ref: '#/components/parameters/after'
- $ref: '#/components/parameters/before'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/count'
responses:
'200':
description: Listing of new posts
content:
application/json:
schema:
$ref: '#/components/schemas/Listing'
/r/{subreddit}/rising:
get:
operationId: getRisingListings
summary: Get Rising Listings
description: >-
Returns a listing of rising posts from the specified subreddit.
Rising posts are those gaining upvotes at a rapid rate.
tags:
- Listings
parameters:
- $ref: '#/components/parameters/subreddit'
- $ref: '#/components/parameters/after'
- $ref: '#/components/parameters/before'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/count'
responses:
'200':
description: Listing of rising posts
content:
application/json:
schema:
$ref: '#/components/schemas/Listing'
/r/{subreddit}/top:
get:
operationId: getTopListings
summary: Get Top Listings
description: >-
Returns a listing of top-scoring posts from the specified subreddit,
filterable by time period.
tags:
- Listings
parameters:
- $ref: '#/components/parameters/subreddit'
- $ref: '#/components/parameters/after'
- $ref: '#/components/parameters/before'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/t'
responses:
'200':
description: Listing of top posts
content:
application/json:
schema:
$ref: '#/components/schemas/Listing'
/r/{subreddit}/controversial:
get:
operationId: getControversialListings
summary: Get Controversial Listings
description: >-
Returns a listing of controversial posts from the specified
subreddit, which are posts with a roughly even mix of upvotes
and downvotes.
tags:
- Listings
parameters:
- $ref: '#/components/parameters/subreddit'
- $ref: '#/components/parameters/after'
- $ref: '#/components/parameters/before'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/count'
- $ref: '#/components/parameters/t'
responses:
'200':
description: Listing of controversial posts
content:
application/json:
schema:
$ref: '#/components/schemas/Listing'
/comments/{article}:
get:
operationId: getComments
summary: Get Comments for a Submission
description: >-
Returns comments for a given submission (article). The response
includes both the submission data and a tree of comments. Use
the sort parameter to control comment ordering.
tags:
- Links & Comments
parameters:
- name: article
in: path
required: true
description: >-
The ID36 of the submission to retrieve comments for.
schema:
type: string
- name: sort
in: query
description: >-
The sorting method for comments.
schema:
type: string
enum:
- confidence
- top
- new
- controversial
- old
- random
- qa
- live
- name: depth
in: query
description: >-
Maximum depth of subtrees in the thread.
schema:
type: integer
- name: context
in: query
description: >-
Number of levels of parent comments to include for a comment permalink.
schema:
type: integer
minimum: 0
maximum: 8
- $ref: '#/components/parameters/limit'
responses:
'200':
description: Submission and comment tree
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Listing'
/api/morechildren:
get:
operationId: getMoreChildren
summary: Retrieve Additional Comments
description: >-
Retrieves additional comments omitted from a base comment tree.
Used to load more comments from a stub returned in a comment
listing.
tags:
- Links & Comments
parameters:
- name: link_id
in: query
required: true
description: >-
The fullname (t3_ prefix) of the submission.
schema:
type: string
- name: children
in: query
required: true
description: >-
A comma-delimited list of comment ID36s to be fetched.
schema:
type: string
- name: sort
in: query
description: >-
The sorting method for comments.
schema:
type: string
enum:
- confidence
- top
- new
- controversial
- old
- random
- qa
- live
- name: api_type
in: query
description: >-
The string json to request JSON response.
schema:
type: string
default: json
responses:
'200':
description: Additional comment data
content:
application/json:
schema:
type: object
/api/submit:
post:
operationId: submit
summary: Submit a New Link or Self-post
description: >-
Submits a new link or self-post to a subreddit. Requires the
submit OAuth scope.
tags:
- Links & Comments
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- sr
- title
- kind
properties:
sr:
type: string
description: >-
The name of the subreddit to submit to.
title:
type: string
description: >-
The title of the submission (max 300 characters).
maxLength: 300
kind:
type: string
description: >-
The type of submission.
enum:
- link
- self
- image
- video
- videogif
url:
type: string
format: uri
description: >-
The URL for a link submission.
text:
type: string
description: >-
The body text for a self-post (markdown).
richtext_json:
type: string
description: >-
The rich text body as JSON for a self-post.
flair_id:
type: string
description: >-
The flair template ID to apply to the submission.
flair_text:
type: string
description: >-
The flair text to apply to the submission.
nsfw:
type: boolean
description: >-
Whether the submission is NSFW.
spoiler:
type: boolean
description: >-
Whether the submission is a spoiler.
resubmit:
type: boolean
description: >-
Whether to allow resubmitting a URL that has already
been submitted.
sendreplies:
type: boolean
description: >-
Whether to send replies to the user's inbox.
api_type:
type: string
default: json
responses:
'200':
description: Submission created
content:
application/json:
schema:
type: object
'403':
description: Permission denied
/api/comment:
post:
operationId: comment
summary: Submit a New Comment
description: >-
Submits a new comment on a submission or in reply to another
comment. Requires the submit OAuth scope.
tags:
- Links & Comments
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- thing_id
- text
properties:
thing_id:
type: string
description: >-
The fullname of the parent thing to comment on.
text:
type: string
description: >-
The body of the comment (markdown).
richtext_json:
type: string
description: >-
The rich text body as JSON.
api_type:
type: string
default: json
responses:
'200':
description: Comment created
content:
application/json:
schema:
type: object
'403':
description: Permission denied
/api/vote:
post:
operationId: vote
summary: Vote on a Submission or Comment
description: >-
Casts a vote on a submission or comment. Direction values are
1 for upvote, -1 for downvote, and 0 to remove the vote.
Requires the vote OAuth scope.
tags:
- Links & Comments
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- id
- dir
properties:
id:
type: string
description: >-
The fullname of the thing to vote on.
dir:
type: integer
description: >-
Vote direction: 1 (upvote), -1 (downvote), 0 (unvote).
enum:
- 1
- 0
- -1
rank:
type: integer
description: >-
An integer greater than 1 (deprecated).
responses:
'200':
description: Vote cast successfully
content:
application/json:
schema:
type: object
'401':
description: Authentication required
/api/save:
post:
operationId: save
summary: Save a Submission or Comment
description: >-
Saves a submission or comment to the authenticated user's saved
items. Requires the save OAuth scope.
tags:
- Links & Comments
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- id
properties:
id:
type: string
description: >-
The fullname of the thing to save.
category:
type: string
description: >-
A category name for the saved item (Reddit Gold feature).
responses:
'200':
description: Item saved successfully
/api/unsave:
post:
operationId: unsave
summary: Unsave a Submission or Comment
description: >-
Removes a submission or comment from the authenticated user's
saved items. Requires the save OAuth scope.
tags:
- Links & Comments
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- id
properties:
id:
type: string
description: >-
The fullname of the thing to unsave.
responses:
'200':
description: Item unsaved successfully
/api/hide:
post:
operationId: hide
summary: Hide a Submission
description: >-
Hides a submission from the authenticated user's listings.
Requires the report OAuth scope.
tags:
- Links & Comments
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- id
properties:
id:
type: string
description: >-
A comma-separated list of fullnames to hide.
responses:
'200':
description: Submission hidden successfully
/api/unhide:
post:
operationId: unhide
summary: Unhide a Submission
description: >-
Unhides a previously hidden submission. Requires the report
OAuth scope.
tags:
- Links & Comments
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- id
properties:
id:
type: string
description: >-
A comma-separated list of fullnames to unhide.
responses:
'200':
description: Submission unhidden successfully
/api/del:
post:
operationId: del
summary: Delete a Submission or Comment
description: >-
Deletes a submission or comment authored by the authenticated user.
Requires the edit OAuth scope.
tags:
- Links & Comments
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- id
properties:
id:
type: string
description: >-
The fullname of the thing to delete.
responses:
'200':
description: Item deleted successfully
/api/editusertext:
post:
operationId: editUserText
summary: Edit a Self-post or Comment
description: >-
Edits the body text of a self-post or comment authored by the
authenticated user. Requires the edit OAuth scope.
tags:
- Links & Comments
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- thing_id
- text
properties:
thing_id:
type: string
description: >-
The fullname of the thing to edit.
text:
type: string
description: >-
The new body text (markdown).
api_type:
type: string
default: json
responses:
'200':
description: Text edited successfully
content:
application/json:
schema:
type: object
/api/report:
post:
operationId: report
summary: Report a Submission or Comment
description: >-
Reports a submission or comment to the moderators of the
subreddit. Requires the report OAuth scope.
tags:
- Links & Comments
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- thing_id
properties:
thing_id:
type: string
description: >-
The fullname of the thing to report.
reason:
type: string
description: >-
The reason for reporting (max 100 characters).
maxLength: 100
other_reason:
type: string
description: >-
A custom reason for reporting (max 100 characters).
maxLength: 100
site_reason:
type: string
description: >-
A site rule violation reason.
rule_reason:
type: string
description: >-
A subreddit rule violation reason.
api_type:
type: string
default: json
responses:
'200':
description: Report submitted
/message/inbox:
get:
operationId: getInbox
summary: Get Inbox Messages
description: >-
Returns a listing of the authenticated user's inbox messages,
including both private messages and comment replies.
Requires the privatemessages OAuth scope.
tags:
- Messages
parameters:
- $ref: '#/components/parameters/after'
- $ref: '#/components/parameters/before'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/count'
- name: mark
in: query
description: >-
Whether to mark messages as read.
schema:
type: boolean
default: true
responses:
'200':
description: Listing of inbox messages
content:
application/json:
schema:
$ref: '#/components/schemas/Listing'
/message/unread:
get:
operationId: getUnreadMessages
summary: Get Unread Messages
description: >-
Returns a listing of the authenticated user's unread messages.
Requires the privatemessages OAuth scope.
tags:
- Messages
parameters:
- $ref: '#/components/parameters/after'
- $ref: '#/components/parameters/before'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/count'
- name: mark
in: query
description: >-
Whether to mark messages as read.
schema:
type: boolean
default: true
responses:
'200':
description: Listing of unread messages
content:
application/json:
schema:
$ref: '#/components/schemas/Listing'
/message/sent:
get:
operationId: getSentMessages
summary: Get Sent Messages
description: >-
Returns a listing of the authenticated user's sent messages.
Requires the privatemessages OAuth scope.
tags:
- Messages
parameters:
- $ref: '#/components/parameters/after'
- $ref: '#/components/parameters/before'
- $ref: '#/components/parameters/limit'
- $ref: '#/components/parameters/count'
responses:
'200':
description: Listing of sent messages
content:
application/json:
schema:
$ref: '#/components/schemas/Listing'
/api/compose:
post:
operationId: composeMessage
summary: Compose a Private Message
description: >-
Sends a private message to another user or a subreddit's
moderators. Requires the privatemessages OAuth scope.
tags:
- Messages
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- to
- subject
- text
properties:
to:
type: string
description: >-
The recipient username or /r/subreddit for modmail.
subject:
type: string
description: >-
The subject of the message (max 100 characters).
maxLength: 100
text:
type: string
description: >-
The body of the message (markdown).
api_type:
type: string
default: json
responses:
'200':
description: Message sent successfully
'403':
description: Permission denied
/api/read_message:
post:
operationId: readMessage
summary: Mark Messages As Read
description: >-
Marks one or more messages as read. Requires the privatemessages
OAuth scope.
tags:
- Messages
requestBody:
required: true
content:
application/x-www-form-urlencoded:
schema:
type: object
required:
- id
properties:
id:
type: string
description: >-
A comma-separated list of message fullnames to mark as read.
responses:
'200':
description: Messages marked as read
/api/read_all_messages:
post:
operationId: readAllMessages
summary: Mark All Messages As Read
description: >-
Marks all of the authenticated user's messages as read.
Requires the privatemessages OAuth scope.
tags:
- Messages
responses:
'200':
description: All messages marked as read
/r/{subreddit}/about:
get:
operationId: getSubredditAbout
summary: Get Subreddit Information
description: >-
Returns information about the specified subreddit, including
subscriber count, description, rules, and settings.
tags:
- Subreddits
parameters:
- $ref: '#/components/parameters/subreddit'
responses:
'200':
description: Subreddit information
content:
application/json:
schema:
$ref: '#/components/schemas/Subreddit'
'404':
# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/reddit/refs/heads/main/openapi/reddit-data-api-openapi.yml