A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The Reddit API is how an app or AI agent works with a Reddit account: reading a subreddit's hot, new, or top posts, submitting a post, replying to and voting on comments, and reading or sending private messages. Access is granted through an OAuth 2.0 token carrying a set of scopes, such as read, submit, vote, or privatemessages, and an agent is limited to those scopes and to the subreddits it moderates for any moderator action. Reddit does not push events, so an agent learns about new activity by polling rather than by subscribing.
How an app or AI agent connects to Reddit determines what it can reach. Access runs through an OAuth 2.0 token, and the scopes on that token decide which areas of the account and which moderator powers a call can use.
The REST API answers at https://oauth.reddit.com for any call made with a bearer token. Calls without a token go to www.reddit.com, but every authenticated request must use the oauth.reddit.com host.
Reddit has no event push, so an app or AI agent watches for new posts, comments, and messages by repeatedly calling the new listing and inbox methods and tracking what it has already seen.
A user grants the app a set of scopes, and the app receives an access token that acts on that user's behalf. This is the route for any action tied to a person, such as submitting, voting, or reading the inbox.
The app authenticates as itself with no user, getting a token for read-only access to public data. It cannot submit, vote, or read a user's private content.
The Reddit API is split into areas an agent can act on, such as listings, posts, comments, votes, subreddits, the account, messages, and moderation. Each area has its own methods and its own scope, and some grant access to far more than others.
Read a subreddit's posts sorted by hot, new, top, or rising, and look up posts or comments by their full identifier.
Submit a link or text post, and read a single post with its comment thread.
Reply to a post or comment, edit the text of a comment or post, and delete a comment or post.
Cast or change a vote on a post or comment, and save or unsave content.
Read a subreddit's details, subscribe or unsubscribe, and list the subreddits the account moderates, contributes to, or follows.
Read the authenticated account's identity, read a user's public profile, and add or remove a followed user.
Read the inbox, sent, and unread message folders, and send a private message to another user.
Search posts within a subreddit or across Reddit.
Approve or remove content, and distinguish a post or comment, in subreddits the account moderates.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
ListingsRead a subreddit's posts sorted by hot, new, top, or rising, and look up posts or comments by their full identifier.5 | ||||||
| GET | /r/{subreddit}/hot | Get the hot listing for a subreddit. | read | read | Current | |
Omitting the subreddit returns the hot listing for the account's front page. Paged through the after and before parameters. Acts onlisting Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /r/{subreddit}/new | Get the new listing for a subreddit, sorted by most recent. | read | read | Current | |
Polling this is how an agent discovers new posts, since Reddit pushes no events. Acts onlisting Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /r/{subreddit}/top | Get the top listing for a subreddit over a chosen time window. | read | read | Current | |
The t parameter sets the window, such as hour, day, week, month, year, or all. Acts onlisting Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /r/{subreddit}/rising | Get the rising listing for a subreddit, surfacing posts gaining activity. | read | read | Current | |
Acts onlisting Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /api/info | Look up posts, comments, or subreddits by their full identifier or by URL. | read | read | Current | |
Takes a comma-separated list of fullnames in the id parameter, where a fullname is a type prefix plus an id, such as t3_ for a post and t1_ for a comment. Acts onthing Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PostsSubmit a link or text post, and read a single post with its comment thread.2 | ||||||
| GET | /comments/{article} | Get a single post and the comment tree beneath it. | read | read | Current | |
The article is the post's id without the t3_ prefix. Returns the post followed by its comments. Acts onpost Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/submit | Submit a new link or text post to a subreddit. | write | submit | Current | |
The kind parameter chooses link or self (text). Errors are returned inside a 200 response, such as RATELIMIT when posting too often or SUBREDDIT_NOEXIST for an unknown subreddit. Acts onpost Permission (capability) submitVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
CommentsReply to a post or comment, edit the text of a comment or post, and delete a comment or post.3 | ||||||
| POST | /api/comment | Submit a comment in reply to a post or another comment. | write | submit | Current | |
The thing_id parameter is the fullname of the post or comment being replied to, and text is markdown. Creating a comment uses the submit scope, not edit. Acts oncomment Permission (capability) submitVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/editusertext | Edit the body of an existing text post or comment. | write | edit | Current | |
Only the account's own content can be edited. The thing_id parameter is the fullname of the post or comment. Acts oncomment Permission (capability) editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/del | Delete a post or comment the account authored. | write | edit | Current | |
The id parameter is the fullname of the content to delete. This is a self-delete, separate from a moderator removal. Acts oncomment Permission (capability) editVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Voting & savingCast or change a vote on a post or comment, and save or unsave content.2 | ||||||
| POST | /api/vote | Cast, change, or clear a vote on a post or comment. | write | vote | Current | |
The dir parameter is 1 for an upvote, -1 for a downvote, and 0 to clear. Reddit's rules forbid automated voting that a human did not direct. Acts onvote Permission (capability) voteVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/save | Save a post or comment to the account's saved items. | write | save | Current | |
The id parameter is the fullname. Unsaving uses the companion api/unsave method under the same scope. Acts onsaved item Permission (capability) saveVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SubredditsRead a subreddit's details, subscribe or unsubscribe, and list the subreddits the account moderates, contributes to, or follows.3 | ||||||
| GET | /r/{subreddit}/about | Get a subreddit's details, such as its title, description, and subscriber count. | read | read | Current | |
Acts onsubreddit Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/subscribe | Subscribe to or unsubscribe from a subreddit on the account. | write | subscribe | Current | |
The action parameter is sub or unsub, and sr or sr_name names the subreddit. This changes the account's own subscriptions, not a subreddit's settings. Acts onsubreddit Permission (capability) subscribeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /subreddits/mine/{where} | List the subreddits the account subscribes to, contributes to, or moderates. | read | mysubreddits | Current | |
The where path segment is subscriber, contributor, moderator, or streams. Acts onsubreddit Permission (capability) mysubredditsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Account & usersRead the authenticated account's identity, read a user's public profile, and add or remove a followed user.3 | ||||||
| GET | /api/v1/me | Get the identity of the authenticated account, including username and signup date. | read | identity | Current | |
The identity scope reaches the signed-in account's username and signup date, not its voting or saved history. Acts onaccount Permission (capability) identityVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /user/{username}/about | Get a user's public profile by username. | read | read | Current | |
Returns public profile fields, such as karma and account age. Acts onuser Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /api/v1/me/friends/{username} | Add a user to the account's followed users. | write | subscribe | Current | |
The subscribe scope covers managing followed users, called friends. The companion DELETE on the same path removes a followed user. Acts onuser Permission (capability) subscribeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Private messagesRead the inbox, sent, and unread message folders, and send a private message to another user.2 | ||||||
| GET | /message/inbox | List the messages in the account's inbox. | read | privatemessages | Current | |
The sent and unread folders use the matching message/sent and message/unread methods under the same scope. Acts onmessage Permission (capability) privatemessagesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/compose | Send a private message to another user. | write | privatemessages | Current | |
The to parameter is the recipient username, with subject and text fields. The same scope grants both reading the inbox and sending messages. Acts onmessage Permission (capability) privatemessagesVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SearchSearch posts within a subreddit or across Reddit.1 | ||||||
| GET | /r/{subreddit}/search | Search posts within a subreddit, or across Reddit when no subreddit is given. | read | read | Current | |
The q parameter is the query, and restrict_sr limits results to the named subreddit. Sort and time-window parameters narrow the results. Acts onsearch result Permission (capability) readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
ModerationApprove or remove content, and distinguish a post or comment, in subreddits the account moderates.3 | ||||||
| POST | /api/approve | Approve a post or comment in a subreddit the account moderates. | write | modposts | Current | |
Only works where the account holds moderator powers. The id parameter is the fullname of the content to approve. Acts onpost Permission (capability) modpostsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/remove | Remove a post or comment in a subreddit the account moderates. | write | modposts | Current | |
Moderator removal, separate from the author self-delete at api/del. The spam parameter marks the removal as spam. Acts onpost Permission (capability) modpostsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /api/distinguish | Distinguish or sticky a post or comment as a moderator. | write | modposts | Current | |
The how parameter sets the badge, such as yes for the moderator badge or no to clear it. Acts oncomment Permission (capability) modpostsVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Reddit does not push events to a webhook. An app or AI agent learns about new posts, comments, and messages by polling the listing and inbox methods, so there is no event subscription to register.
| Event | What it signals | Triggered by |
|---|
Reddit limits how fast an app or AI agent can call, through a per-client request quota measured over a rolling window, and reports the current state in response headers on every call.
Reddit sets a per-client request quota rather than a per-user one, so every user running under the same registered app shares one ceiling. The OAuth limit is up to 60 requests per minute, measured as a rolling average over a 10-minute window, which allows short bursts as long as the average holds. The free Data API tier is capped at 100 queries per minute per client identifier, again averaged over 10 minutes. Every response carries the headers X-Ratelimit-Used, X-Ratelimit-Remaining, and X-Ratelimit-Reset, which report requests used, requests left, and seconds until the window resets; an app is expected to watch these and slow down before exceeding the limit. Reddit also requires a unique, descriptive User-Agent in the form platform:appID:version (by /u/username), and warns that default or generic User-Agents are drastically rate limited.
Listing methods page through opaque cursors. The after parameter takes the fullname of the last item seen to fetch the next page, and before pages backward, with limit setting the page size up to 100 and a count parameter tracking the running total. A fullname is a type prefix plus an id, such as t3_ for a post or t1_ for a comment. There is no offset or page number.
Requests and responses are JSON over HTTPS. A listing returns at most 100 items per page. Reddit does not publish a single payload size limit; individual fields, such as a post title or a self-post body, have their own length caps enforced on submission.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 200 | RATELIMIT (in body) | Many write methods report failure inside a 200 response rather than as an HTTP error, returning a json.errors array. A RATELIMIT entry means an action, such as submitting or commenting, was attempted too soon after the last one. | Read the json.errors array on every write response, and wait the period the RATELIMIT message states before retrying. |
| 401 | Unauthorized | The access token is missing, invalid, or expired. | Refresh or re-obtain the OAuth token, then resend with a valid Authorization header. |
| 403 | Forbidden | The token is valid but its scopes do not cover the call, or the account lacks the right, such as moderating a subreddit it does not moderate. | Request the missing scope, or confirm the account holds the needed moderator powers. |
| 429 | Too Many Requests | The per-client request quota was exceeded. The X-Ratelimit-Remaining header is at or near zero and X-Ratelimit-Reset gives the seconds until the window resets. | Watch the X-Ratelimit headers and slow down, then retry after the reset. |
| 404 | Not Found | The subreddit, post, comment, or user does not exist, or is private or banned and not visible to the account. | Confirm the identifier and that the account can see the resource. |
Reddit's API is not versioned by a dated string. There is a single, continuously updated API, with the developer platform and its data terms changed through dated policy announcements rather than version numbers.
Reddit's API has no dated version string. The methods evolve in place, and material change reaches developers through dated developer-platform and data-terms announcements rather than a version header. The entries below mark the notable policy and access changes.
Reddit's new Data API pricing and access rules took effect on Saturday 1 July 2023. Free access became non-commercial only, capped at 100 queries per minute per OAuth client, with commercial use charged at a published per-call rate under a separate agreement. The change followed the 19 June 2023 update to the Data API Terms.
Reddit published updated Data API Terms on Monday 19 June 2023, restricting use of Reddit data, including a prohibition on using it to train machine learning or AI models without express written approval, and setting the framework for the paid tiers that followed.
An integration tracks change through Reddit's developer platform announcements, not a version header.
Reddit developer platform updates ↗Bollard AI sits between a team's AI agents and Reddit. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.