Create a Reddit Post Programmatically
Create a Reddit text or link post through a REST call. Handles session cookies, CSRF tokens and subreddit rule rejections, and refuses unsupported post kinds by name instead of silently downgrading them.
/api/reddit/submit$0.012 / callCreate a post in a subreddit as the authenticated caller. Serves text (self) and
link posts.
Not yet verified end to end. The route is unit-tested and its request shape is derived from the live router, but no post has been created through it against a real Reddit account. A write that fails does so under your account, in a real subreddit. Talk to support before you build on this, and we will verify it with you.
Request Body
Cookies are passed as flat top-level fields.
| Field | Type | Required | Description |
|---|---|---|---|
subreddit | string | yes | Target subreddit name, without the r/ prefix |
kind | string | yes | self for a text post, link for a URL post |
title | string | yes | Post title |
text | string | no | Body text. Used when kind is self. |
url | string | no | Target URL. Used when kind is link. |
nsfw | boolean | no | Mark the post NSFW |
spoiler | boolean | no | Mark the post a spoiler |
sendreplies | boolean | no | Send reply notifications to the author inbox |
flair_id | string | no | Subreddit flair template id |
flair_text | string | no | Flair text, where the subreddit allows it |
reddit_session | string | yes | Session cookie from /api/reddit/login |
loid | string | yes | Long-lived account identifier cookie |
Which kinds are served
self and link are served. Poll, image and video are refused by name with a 400,
never silently downgraded to a text post. A caller who asked for a poll and quietly
received a text post would have no way to discover that until a human looked at the
subreddit, so the refusal is deliberate and explicit.
Those three need a different upstream path: polls use Reddit's own poll endpoint, and image and video require a media lease and an upload before the post is created, with the result delivered asynchronously.
Errors
| Status | Meaning |
|---|---|
400 | subreddit, kind or title missing, a kind this endpoint does not serve (UNSUPPORTED_POST_KIND), or a malformed field |
401 | Missing Bearer token |
402 | Insufficient credits |
403 | Invalid Bearer token |
429 | Rate limited |
502 | Reddit refused the post: a subreddit rule (NOT_ALLOWED_IN_SUBREDDIT), Reddit's own rate limit (REDDIT_RATELIMIT), a generic refusal (REDDIT_REFUSED), or a captcha demand (CAPTCHA_REQUIRED) |
503 | No session could be acquired from the pool before the timeout |
500 | Unexpected server error |
A subreddit rejection is a 502, not a 403. 403 means this API rejected your
Bearer token and never reached Reddit at all. That distinction matters when you write the
handler: a 502 carrying NOT_ALLOWED_IN_SUBREDDIT is Reddit's final answer about this
post, so retrying it reproduces the same refusal, while a 503 is our pool and is worth
retrying. Treating the subreddit refusal as a generic transport failure is the one
mistake that costs a real account a repeated rejected post.
A rule rejection carries Reddit's own machine-readable error in reddit_errors, so a
karma requirement, an account-age gate or a banned link domain is distinguishable from a
transport failure rather than collapsing into one opaque error. CAPTCHA_REQUIRED is
terminal for this endpoint by design: it does not solve captchas, so retrying the same
way will not help.
Independent third-party API for developers and researchers. Not affiliated with, endorsed by, or sponsored by Reddit, Inc.
Authenticated reads
Send your Reddit session as headers on the twelve read endpoints that accept one, to see private, restricted and member-only subreddits, plus your own feed, saved, hidden and upvoted. Five of the twelve need a session and cannot be served without one. Optional, additive, and existing calls are unchanged.
CommentHot
Post a comment on any Reddit thread programmatically. Handles reCAPTCHA, CSRF tokens, and rich-text encoding for you, just send post URL and text.