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': description: Subreddit not found /r/{subreddit}/about/rules: get: operationId: getSubredditRules summary: Get Subreddit Rules description: >- Returns the rules defined for the specified subreddit. tags: - Subreddits parameters: - $ref: '#/components/parameters/subreddit' responses: '200': description: Subreddit rules content: application/json: schema: type: object properties: rules: type: array items: $ref: '#/components/schemas/SubredditRule' site_rules: type: array items: type: string /subreddits/mine/subscriber: get: operationId: getMySubreddits summary: Get Subscribed Subreddits description: >- Returns a listing of subreddits the authenticated user is subscribed to. Requires the mysubreddits OAuth scope. tags: - Subreddits parameters: - $ref: '#/components/parameters/after' - $ref: '#/components/parameters/before' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/count' responses: '200': description: Listing of subscribed subreddits content: application/json: schema: $ref: '#/components/schemas/Listing' /api/subscribe: post: operationId: subscribe summary: Subscribe or Unsubscribe From a Subreddit description: >- Subscribes to or unsubscribes from a subreddit. Requires the subscribe OAuth scope. tags: - Subreddits requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - action - sr_name properties: action: type: string description: >- The subscription action to perform. enum: - sub - unsub sr_name: type: string description: >- The name of the subreddit. skip_initial_defaults: type: boolean description: >- Whether to skip adding default subreddits for new accounts. responses: '200': description: Subscription updated /subreddits/search: get: operationId: searchSubreddits summary: Search Subreddits description: >- Searches for subreddits by name and description. tags: - Search parameters: - name: q in: query required: true description: >- The search query string. schema: type: string - $ref: '#/components/parameters/after' - $ref: '#/components/parameters/before' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/count' responses: '200': description: Search results content: application/json: schema: $ref: '#/components/schemas/Listing' /r/{subreddit}/search: get: operationId: search summary: Search Submissions description: >- Searches for submissions within a specific subreddit or across all of Reddit. Supports sorting and time filtering. tags: - Search parameters: - $ref: '#/components/parameters/subreddit' - name: q in: query required: true description: >- The search query string. schema: type: string - name: sort in: query description: >- The sorting method for search results. schema: type: string enum: - relevance - hot - top - new - comments - $ref: '#/components/parameters/t' - name: restrict_sr in: query description: >- Whether to restrict the search to the specified subreddit. schema: type: boolean default: true - name: type in: query description: >- The type of results to return. schema: type: string enum: - sr - link - user - $ref: '#/components/parameters/after' - $ref: '#/components/parameters/before' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/count' responses: '200': description: Search results content: application/json: schema: $ref: '#/components/schemas/Listing' /user/{username}/about: get: operationId: getUserAbout summary: Get User Profile description: >- Returns public information about the specified user, including karma, account age, and display preferences. tags: - Users parameters: - name: username in: path required: true description: >- The username of the user to look up. schema: type: string responses: '200': description: User profile information content: application/json: schema: $ref: '#/components/schemas/Account' '404': description: User not found /user/{username}/submitted: get: operationId: getUserSubmitted summary: Get User Submissions description: >- Returns a listing of submissions posted by the specified user. tags: - Users parameters: - name: username in: path required: true description: >- The username to get submissions for. schema: type: string - name: sort in: query description: >- The sorting method. schema: type: string enum: - hot - new - top - controversial - $ref: '#/components/parameters/t' - $ref: '#/components/parameters/after' - $ref: '#/components/parameters/before' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/count' responses: '200': description: Listing of user submissions content: application/json: schema: $ref: '#/components/schemas/Listing' /user/{username}/comments: get: operationId: getUserComments summary: Get User Comments description: >- Returns a listing of comments posted by the specified user. tags: - Users parameters: - name: username in: path required: true description: >- The username to get comments for. schema: type: string - name: sort in: query description: >- The sorting method. schema: type: string enum: - hot - new - top - controversial - $ref: '#/components/parameters/t' - $ref: '#/components/parameters/after' - $ref: '#/components/parameters/before' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/count' responses: '200': description: Listing of user comments content: application/json: schema: $ref: '#/components/schemas/Listing' /user/{username}/trophies: get: operationId: getUserTrophies summary: Get User Trophies description: >- Returns a list of trophies for the specified user. tags: - Users parameters: - name: username in: path required: true description: >- The username to get trophies for. schema: type: string responses: '200': description: User trophies content: application/json: schema: type: object /r/{subreddit}/about/moderators: get: operationId: getSubredditModerators summary: Get Subreddit Moderators description: >- Returns a listing of the moderators of the specified subreddit. tags: - Moderation parameters: - $ref: '#/components/parameters/subreddit' responses: '200': description: Moderator listing content: application/json: schema: type: object /r/{subreddit}/about/modqueue: get: operationId: getModqueue summary: Get Moderation Queue description: >- Returns a listing of items in the subreddit's moderation queue. Items include submissions and comments that have been reported or caught by spam filters. Requires the modposts OAuth scope. tags: - Moderation parameters: - $ref: '#/components/parameters/subreddit' - name: type in: query description: >- Filter by type of content in the queue. schema: type: string enum: - links - comments - $ref: '#/components/parameters/after' - $ref: '#/components/parameters/before' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/count' responses: '200': description: Moderation queue listing content: application/json: schema: $ref: '#/components/schemas/Listing' /r/{subreddit}/about/reports: get: operationId: getReports summary: Get Reported Items description: >- Returns a listing of reported items in the subreddit. Requires the modposts OAuth scope. tags: - Moderation 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 reported items content: application/json: schema: $ref: '#/components/schemas/Listing' /r/{subreddit}/about/spam: get: operationId: getSpam summary: Get Spam Items description: >- Returns a listing of items marked as spam in the subreddit. Requires the modposts OAuth scope. tags: - Moderation 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 spam items content: application/json: schema: $ref: '#/components/schemas/Listing' /r/{subreddit}/about/log: get: operationId: getModLog summary: Get Moderation Log description: >- Returns a listing of moderation actions taken in the subreddit. Requires the modlog OAuth scope. tags: - Moderation parameters: - $ref: '#/components/parameters/subreddit' - name: mod in: query description: >- Filter by moderator username. schema: type: string - name: type in: query description: >- Filter by moderation action type. schema: type: string - $ref: '#/components/parameters/after' - $ref: '#/components/parameters/before' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/count' responses: '200': description: Moderation log listing content: application/json: schema: $ref: '#/components/schemas/Listing' /api/approve: post: operationId: approve summary: Approve a Submission or Comment description: >- Approves a submission or comment that was removed or reported. Requires the modposts OAuth scope. tags: - Moderation 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 approve. responses: '200': description: Item approved /api/remove: post: operationId: remove summary: Remove a Submission or Comment description: >- Removes a submission or comment from public listings. Requires the modposts OAuth scope. tags: - Moderation requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - id - spam properties: id: type: string description: >- The fullname of the thing to remove. spam: type: boolean description: >- Whether to mark the item as spam. responses: '200': description: Item removed /r/{subreddit}/about/banned: get: operationId: getBannedUsers summary: Get Banned Users description: >- Returns a listing of users banned from the specified subreddit. Requires the modcontributors OAuth scope. tags: - Moderation 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 banned users content: application/json: schema: type: object /r/{subreddit}/api/flair: post: operationId: setFlair summary: Set User Flair description: >- Sets the flair for a user in the specified subreddit. Requires the modflair OAuth scope (or flair scope for self-flair). tags: - Flair parameters: - $ref: '#/components/parameters/subreddit' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object properties: name: type: string description: >- The username to set flair for. text: type: string description: >- The flair text. css_class: type: string description: >- The CSS class for the flair. api_type: type: string default: json responses: '200': description: Flair set successfully /r/{subreddit}/api/flairselector: post: operationId: getFlairSelector summary: Get Available Flair Options description: >- Returns available flair options for a user or link in the specified subreddit. tags: - Flair parameters: - $ref: '#/components/parameters/subreddit' requestBody: content: application/x-www-form-urlencoded: schema: type: object properties: link: type: string description: >- The fullname of a link to get flair options for. name: type: string description: >- The username to get flair options for. responses: '200': description: Available flair options content: application/json: schema: type: object /r/{subreddit}/wiki/{page}: get: operationId: getWikiPage summary: Get a Wiki Page description: >- Returns the content of a wiki page in the specified subreddit. Requires the wikiread OAuth scope. tags: - Wiki parameters: - $ref: '#/components/parameters/subreddit' - name: page in: path required: true description: >- The name of the wiki page. schema: type: string responses: '200': description: Wiki page content content: application/json: schema: $ref: '#/components/schemas/WikiPage' '404': description: Wiki page not found /r/{subreddit}/wiki/pages: get: operationId: getWikiPages summary: List Wiki Pages description: >- Returns a listing of all wiki pages in the specified subreddit. Requires the wikiread OAuth scope. tags: - Wiki parameters: - $ref: '#/components/parameters/subreddit' responses: '200': description: List of wiki pages content: application/json: schema: type: object properties: kind: type: string data: type: array items: type: string /r/{subreddit}/api/wiki/edit: post: operationId: editWikiPage summary: Edit a Wiki Page description: >- Edits the content of a wiki page in the specified subreddit. Requires the wikiedit OAuth scope. tags: - Wiki parameters: - $ref: '#/components/parameters/subreddit' requestBody: required: true content: application/x-www-form-urlencoded: schema: type: object required: - page - content properties: page: type: string description: >- The name of the wiki page to edit. content: type: string description: >- The new content for the wiki page (markdown). reason: type: string description: >- The edit reason (max 256 characters). maxLength: 256 previous: type: string description: >- The revision ID that this edit is based on. responses: '200': description: Wiki page edited successfully /r/{subreddit}/wiki/revisions/{page}: get: operationId: getWikiPageRevisions summary: Get Wiki Page Revision History description: >- Returns the revision history for a wiki page. Requires the wikiread OAuth scope. tags: - Wiki parameters: - $ref: '#/components/parameters/subreddit' - name: page in: path required: true description: >- The name of the wiki page. schema: type: string - $ref: '#/components/parameters/after' - $ref: '#/components/parameters/before' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/count' responses: '200': description: Revision history listing content: application/json: schema: $ref: '#/components/schemas/Listing' /api/v1/scopes: get: operationId: getScopes summary: Get Available Oauth Scopes description: >- Returns a listing of all available OAuth scopes and their descriptions. tags: - Account responses: '200': description: Available OAuth scopes content: application/json: schema: type: object additionalProperties: type: object properties: description: type: string id: type: string name: type: string components: securitySchemes: oauth2: type: oauth2 description: >- Reddit uses OAuth 2.0 for authentication. All API requests must include a valid access token obtained through one of the supported OAuth grant types. flows: authorizationCode: authorizationUrl: https://www.reddit.com/api/v1/authorize tokenUrl: https://www.reddit.com/api/v1/access_token scopes: identity: Access user identity edit: Edit and delete content flair: Set user and link flair history: Access voting history modconfig: Manage subreddit configuration modflair: Manage subreddit flair modlog: Access moderation log modposts: Approve and remove content modwiki: Manage wiki pages mysubreddits: Access subscribed subreddits privatemessages: Access private messages read: Read content report: Report content save: Save and unsave content submit: Submit content subscribe: Manage subscriptions vote: Vote on content wikiedit: Edit wiki pages wikiread: Read wiki pages parameters: subreddit: name: subreddit in: path required: true description: >- The name of the subreddit. schema: type: string after: name: after in: query description: >- The fullname of a thing used as an anchor for pagination. Returns results after this item. schema: type: string before: name: before in: query description: >- The fullname of a thing used as an anchor for pagination. Returns results before this item. schema: type: string limit: name: limit in: query description: >- The maximum number of items to return (default 25, max 100). schema: type: integer default: 25 minimum: 1 maximum: 100 count: name: count in: query description: >- A positive integer indicating the number of items already seen in this listing, used for pagination numbering. schema: type: integer minimum: 0 t: name: t in: query description: >- The time period for filtering results. schema: type: string enum: - hour - day - week - month - year - all schemas: Listing: type: object description: >- A Reddit listing is a paginated collection of things. Listings contain a data object with children and pagination information. properties: kind: type: string description: >- The kind identifier, always "Listing". enum: - Listing data: type: object properties: after: type: string nullable: true description: >- The fullname of the next item for forward pagination. before: type: string nullable: true description: >- The fullname of the previous item for backward pagination. dist: type: integer description: >- The number of items in this listing. modhash: type: string description: >- A modhash for CSRF protection. children: type: array description: >- The list of things in this listing. items: $ref: '#/components/schemas/Thing' Thing: type: object description: >- A Reddit thing is the base object type. All Reddit objects (comments, links, subreddits, etc.) are things with a kind and data payload. properties: kind: type: string description: >- The kind identifier (t1 for comment, t2 for account, t3 for link, t4 for message, t5 for subreddit, t6 for award). enum: - t1 - t2 - t3 - t4 - t5 - t6 data: type: object description: >- The thing's data payload, varying by kind. Account: type: object description: >- Represents a Reddit user account with profile and karma information. properties: id: type: string description: >- The account's unique ID36. name: type: string description: >- The account's username. created_utc: type: number format: double description: >- The Unix timestamp of when the account was created. link_karma: type: integer description: >- Total link karma earned. comment_karma: type: integer description: >- Total comment karma earned. is_gold: type: boolean description: >- Whether the user has Reddit Premium. is_mod: type: boolean description: >- Whether the user is a moderator of any subreddit. has_verified_email: type: boolean description: >- Whether the user has a verified email address. icon_img: type: string format: uri description: >- URL of the user's avatar image. subreddit: type: object description: >- The user's profile subreddit information. over_18: type: boolean description: >- Whether the user has opted into viewing NSFW content. Subreddit: type: object description: >- Represents a Reddit subreddit community with its configuration and metadata. properties: kind: type: string description: >- The thing kind, always t5. data: type: object properties: id: type: string description: >- The subreddit's unique ID36. display_name: type: string description: >- The subreddit's display name without the r/ prefix. title: type: string description: >- The subreddit's title. public_description: type: string description: >- The subreddit's public description shown in search results. description: type: string description: >- The subreddit's full sidebar description (markdown). subscribers: type: integer description: >- The number of subscribers. accounts_active: type: integer description: >- The approximate number of users currently active. created_utc: type: number format: double description: >- The Unix timestamp of when the subreddit was created. over18: type: boolean description: >- Whether the subreddit is marked as NSFW. subreddit_type: type: string description: >- The subreddit's access type. enum: - public - private - restricted - gold_restricted - archived url: type: string description: >- The subreddit's URL path (e.g., /r/example/). icon_img: type: string format: uri description: >- URL of the subreddit's icon image. banner_img: type: string format: uri description: >- URL of the subreddit's banner image. SubredditRule: type: object description: >- Represents a rule defined for a subreddit. properties: kind: type: string description: >- The rule kind (link, comment, or all). enum: - link - comment - all short_name: type: string description: >- A short name for the rule. description: type: string description: >- The full description of the rule (markdown). violation_reason: type: string description: >- The reason shown when content is reported for this rule. created_utc: type: number format: double description: >- The Unix timestamp of when the rule was created. priority: type: integer description: >- The display priority of the rule. KarmaBreakdown: type: object description: >- Karma breakdown for a single subreddit. properties: sr: type: string description: >- The subreddit name. comment_karma: type: integer description: >- Comment karma earned in this subreddit. link_karma: type: integer description: >- Link karma earned in this subreddit. WikiPage: type: object description: >- Represents a wiki page in a subreddit. properties: kind: type: string description: >- The kind identifier. data: type: object properties: content_md: type: string description: >- The wiki page content in markdown format. content_html: type: string description: >- The wiki page content rendered as HTML. revision_by: type: object description: >- The user who made the last revision. revision_date: type: number format: double description: >- The Unix timestamp of the last revision. may_revise: type: boolean description: >- Whether the current user can edit this wiki page.