{ "openapi": "3.1.0", "info": { "title": "Redditapis API", "version": "1.0.0", "description": "HTTP API to read from and write to Reddit over plain HTTP with Bearer auth and JSON — no OAuth. Fetch subreddit posts, search posts/communities/comments/media/users, read post comment trees and user profiles, log in to obtain session cookies, then comment, vote, update a profile, and send DMs. Pay per call: GET reads $0.002, vote $0.005, writes (login, comment, profile) $0.012, DM actions $0.025, and account reads free.", "termsOfService": "https://www.redditapis.com/terms-of-service", "contact": { "name": "Redditapis", "url": "https://www.redditapis.com" } }, "servers": [ { "url": "https://api.redditapis.com", "description": "Production" } ], "security": [ { "bearerAuth": [] } ], "tags": [ { "name": "Listings & Search", "description": "Subreddit post listings and full-text search across posts, communities, comments, media, and users." }, { "name": "Posts", "description": "Single post details and full comment trees." }, { "name": "Users", "description": "Public user profiles and recent comments." }, { "name": "Auth", "description": "Log in with a username + password to obtain the session cookies used by write, vote, profile, and DM actions." }, { "name": "Write", "description": "Post comments and cast votes on behalf of a logged-in account." }, { "name": "Profile", "description": "Update the logged-in account's bio, display name, avatar, and banner." }, { "name": "Direct Messages", "description": "Send DMs and read the logged-in account's DM threads and messages." }, { "name": "Account", "description": "Read your account balance, usage, and payment history. Free." } ], "paths": { "/api/reddit/posts": { "get": { "operationId": "reddit-posts", "summary": "Subreddit Posts", "description": "Fetch posts from a subreddit. Supports every Reddit sort tab: new, hot, top, rising, controversial, best. Cost: $0.002 per call.", "tags": [ "Listings & Search" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.002, "parameters": [ { "name": "subreddit", "in": "query", "required": true, "description": "Subreddit name (no r/ prefix)", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "new (default) | hot | top | rising | controversial | best", "schema": { "type": "string" } }, { "name": "t", "in": "query", "required": false, "description": "Timeframe for sort=top/controversial: hour | day | week | month | year | all", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of results to return, 1-100 (default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "after", "in": "query", "required": false, "description": "Pagination cursor (e.g. t3_xxx). Reddit caps a single listing at roughly 1000 posts; past that `after` returns null even when more history exists. Narrow by sort tab, timeframe (sort=top&t=...) or search to reach further.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/reddit/sub/{name}/top": { "get": { "operationId": "reddit-sub-top", "summary": "Top Posts", "description": "Top posts of a subreddit for a timeframe. Cost: $0.002 per call.", "tags": [ "Listings & Search" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.002, "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Subreddit name (no r/ prefix)", "schema": { "type": "string" } }, { "name": "t", "in": "query", "required": false, "description": "day | week (default) | month | year | all", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of results to return, 1-100 (default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "after", "in": "query", "required": false, "description": "Pagination cursor (e.g. t3_xxx). Reddit caps a single listing at roughly 1000 posts; past that `after` returns null even when more history exists. Narrow by sort tab, timeframe (sort=top&t=...) or search to reach further.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/reddit/search": { "get": { "operationId": "reddit-search", "summary": "Search Posts", "description": "Full-text post search, optionally scoped to a subreddit. Cost: $0.002 per call.", "tags": [ "Listings & Search" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.002, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query", "schema": { "type": "string" } }, { "name": "subreddit", "in": "query", "required": false, "description": "Restrict to a subreddit", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "relevance | new | hot | top | comments", "schema": { "type": "string" } }, { "name": "t", "in": "query", "required": false, "description": "hour | day | week | month | year | all", "schema": { "type": "string" } }, { "name": "nsfw", "in": "query", "required": false, "description": "true = include NSFW results (Safe Search off)", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of results to return, 1-100 (default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "after", "in": "query", "required": false, "description": "Pagination cursor (e.g. t3_xxx). Reddit caps a single listing at roughly 1000 posts; past that `after` returns null even when more history exists. Narrow by sort tab, timeframe (sort=top&t=...) or search to reach further.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/reddit/search/communities": { "get": { "operationId": "reddit-search-communities", "summary": "Search Communities", "description": "Search subreddits (communities) by name and topic. Cost: $0.002 per call.", "tags": [ "Listings & Search" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.002, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query", "schema": { "type": "string" } }, { "name": "nsfw", "in": "query", "required": false, "description": "true = include NSFW results (Safe Search off)", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of results to return, 1-100 (default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "after", "in": "query", "required": false, "description": "Pagination cursor (e.g. t3_xxx). Reddit caps a single listing at roughly 1000 posts; past that `after` returns null even when more history exists. Narrow by sort tab, timeframe (sort=top&t=...) or search to reach further.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/reddit/search/comments": { "get": { "operationId": "reddit-search-comments", "summary": "Search Comments", "description": "Search Reddit by COMMENT text. Reddit matches against comments and returns the PARENT POSTS, so results are posts whose discussion mentions your query. Surfaces threads plain post search misses. Cost: $0.002 per call.", "tags": [ "Listings & Search" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.002, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "relevance | new | top | comments", "schema": { "type": "string" } }, { "name": "t", "in": "query", "required": false, "description": "hour | day | week | month | year | all", "schema": { "type": "string" } }, { "name": "nsfw", "in": "query", "required": false, "description": "true = include NSFW results (Safe Search off)", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of results to return, 1-100 (default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "after", "in": "query", "required": false, "description": "Pagination cursor (e.g. t3_xxx). Reddit caps a single listing at roughly 1000 posts; past that `after` returns null even when more history exists. Narrow by sort tab, timeframe (sort=top&t=...) or search to reach further.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/reddit/search/comments/deep": { "get": { "operationId": "reddit-search-comments-deep", "summary": "Deep Comment Search", "description": "Genuine comment search. Takes the parent posts from comment search, fetches each post's comment tree, and returns the ACTUAL comments whose body matches your query, with body, score, author, a comment-deep permalink, and the parent post. Premium: one comment-search read plus up to `limit` comment-tree reads. Best-effort: a deleted or deep-tree comment may be missed (meta.truncated flags a depth-limited tree). Cost: $0.02 per call.", "tags": [ "Listings & Search" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.02, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "relevance | new | top | comments", "schema": { "type": "string" } }, { "name": "t", "in": "query", "required": false, "description": "hour | day | week | month | year | all", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of parent POSTS to expand, 1-10 (default 5). Each is one comment-tree fetch.", "schema": { "type": "string" } }, { "name": "nsfw", "in": "query", "required": false, "description": "true = include NSFW results (Safe Search off)", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/reddit/search/media": { "get": { "operationId": "reddit-search-media", "summary": "Search Media", "description": "Search posts and return only those with image, video, or gallery media. Cost: $0.002 per call.", "tags": [ "Listings & Search" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.002, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query", "schema": { "type": "string" } }, { "name": "kind", "in": "query", "required": false, "description": "all (default) | image | video | gallery", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "relevance | new | hot | top | comments", "schema": { "type": "string" } }, { "name": "t", "in": "query", "required": false, "description": "hour | day | week | month | year | all", "schema": { "type": "string" } }, { "name": "nsfw", "in": "query", "required": false, "description": "true = include NSFW results (Safe Search off)", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Raw search posts to scan before media filtering, 1-100 (default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "after", "in": "query", "required": false, "description": "Pagination cursor (e.g. t3_xxx). Reddit caps a single listing at roughly 1000 posts; past that `after` returns null even when more history exists. Narrow by sort tab, timeframe (sort=top&t=...) or search to reach further.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/reddit/search/users": { "get": { "operationId": "reddit-search-users", "summary": "Search Users", "description": "Search users by username substring. Cost: $0.002 per call.", "tags": [ "Listings & Search" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.002, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search query (username substring match)", "schema": { "type": "string" } }, { "name": "nsfw", "in": "query", "required": false, "description": "true = include NSFW results (Safe Search off)", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of results to return, 1-100 (default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "after", "in": "query", "required": false, "description": "Pagination cursor (e.g. t3_xxx). Reddit caps a single listing at roughly 1000 posts; past that `after` returns null even when more history exists. Narrow by sort tab, timeframe (sort=top&t=...) or search to reach further.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/reddit/post/{id}": { "get": { "operationId": "reddit-post-by-id", "summary": "Post by ID", "description": "Fetch a single post's details by its Reddit id. Cost: $0.002 per call.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.002, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Reddit post id (e.g. 1sgjld3)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/reddit/comments": { "get": { "operationId": "reddit-comments", "summary": "Post Comments", "description": "Fetch the full comment tree of a post by its permalink. Cost: $0.002 per call.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.002, "parameters": [ { "name": "permalink", "in": "query", "required": true, "description": "Post permalink (e.g. /r/X/comments/abc/title/)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/reddit/post/{id}/comments": { "get": { "operationId": "reddit-post-comments-by-id", "summary": "Post Comment Tree by ID", "description": "Fetch a post's full comment tree by its Reddit post id (no permalink needed). Returns the post plus native Reddit t1 comment nodes with nested replies. Cost: $0.002 per call.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.002, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Reddit post id (e.g. 1sgjld3)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/reddit/comments/{postId}": { "get": { "operationId": "reddit-comments-by-post-id", "summary": "Post Comment Tree by ID (alias)", "description": "Alias of GET /api/reddit/post/{postId}/comments — identical response shape and identical $0.002 price. Provided so the three intuitive comment URL shapes all resolve: /comments?permalink=…, /post/{postId}/comments, and /comments/{postId}. Does not affect GET /api/reddit/comments?permalink=, which remains the permalink-based form. Cost: $0.002 per call.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.002, "parameters": [ { "name": "postId", "in": "path", "required": true, "description": "Reddit post id (e.g. 1sgjld3)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/reddit/comment/{id}": { "get": { "operationId": "reddit-comment-by-id", "summary": "Comment by ID", "description": "Fetch a single comment by its Reddit comment id. Returns the native Reddit t1 comment node (body, author, score), or 404 if it does not exist. Cost: $0.002 per call.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.002, "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Reddit comment id, the t1 fullname suffix (e.g. abc123)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/reddit/comments/verify": { "post": { "operationId": "reddit-comments-verify", "summary": "Batch Comment Verify", "description": "Check whether up to 100 comments are still live in a single call, instead of one call per comment. Every requested id comes back with an explicit status (live, deleted, removed, or not_found) — ids Reddit cannot resolve are backfilled as not_found rather than silently dropped. A POST only because 100 ids do not fit in a query string; it is a read, and bills at the flat $0.002 read rate no matter the batch size. Cost: $0.002 per call.", "tags": [ "Posts" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.002, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 100, "description": "1-100 comment ids. Bare ids (\"n1abc2d\") and t1_-prefixed fullnames (\"t1_n1abc2d\") are both accepted and may be mixed." } }, "required": [ "ids" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/api/reddit/user/{name}": { "get": { "operationId": "reddit-user", "summary": "User Profile", "description": "Fetch a user's public profile, karma, and account age. Cost: $0.002 per call.", "tags": [ "Users" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.002, "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Reddit username (no u/ prefix)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/reddit/user/{name}/comments": { "get": { "operationId": "reddit-user-comments", "summary": "User Comments", "description": "Fetch a user's recent comments. Cost: $0.002 per call.", "tags": [ "Users" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.002, "parameters": [ { "name": "name", "in": "path", "required": true, "description": "Reddit username", "schema": { "type": "string" } }, { "name": "sort", "in": "query", "required": false, "description": "new (default) | top | controversial", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Number of results to return, 1-100 (default 25)", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "after", "in": "query", "required": false, "description": "Pagination cursor (e.g. t3_xxx). Reddit caps a single listing at roughly 1000 posts; past that `after` returns null even when more history exists. Narrow by sort tab, timeframe (sort=top&t=...) or search to reach further.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/reddit/login": { "post": { "operationId": "reddit-login", "summary": "Reddit API Login", "description": "Log in with a Reddit username + password (and TOTP secret for 2FA accounts) to obtain the session cookies used by the write, vote, profile, and DM endpoints. Cost: $0.012 per call.", "tags": [ "Auth" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.012, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "username": { "type": "string", "description": "Reddit username or email" }, "password": { "type": "string", "description": "Account password" }, "totp_secret": { "type": "string", "description": "Base32 TOTP secret for accounts with 2FA enabled. Omit if 2FA is off." }, "method": { "type": "string", "description": "http (default) | browser. Use browser for the most compatible write-session cookies." }, "proxy": { "description": "Sticky IP for this account — match the proxy used for /api/reddit/login. Object { server, username?, password? } or a proxy URL string.", "oneOf": [ { "type": "object", "properties": { "server": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" } }, "required": [ "server" ] }, { "type": "string" } ] } }, "required": [ "username", "password" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/api/reddit/comment": { "post": { "operationId": "reddit-comment", "summary": "Post Comment", "description": "Post a comment on any Reddit post. Plain text is rich-text encoded automatically. Cost: $0.012 per call.", "tags": [ "Write" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.012, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "post_url": { "type": "string", "description": "Any reddit.com post URL (new or old UI)" }, "text": { "type": "string", "description": "Comment text — plain text is rich-text encoded automatically" }, "reddit_session": { "type": "string", "description": "Account session cookie (from /api/reddit/login)" }, "loid": { "type": "string", "description": "Account loid cookie (from /api/reddit/login)" }, "token_v2": { "type": "string", "description": "Reddit token_v2 cookie" }, "csrf_token": { "type": "string", "description": "Reddit CSRF token cookie" }, "edgebucket": { "type": "string", "description": "edgebucket cookie" }, "csv": { "type": "string", "description": "csv cookie" }, "session_tracker": { "type": "string", "description": "session_tracker cookie" }, "proxy": { "description": "Sticky IP for this account — match the proxy used for /api/reddit/login. Object { server, username?, password? } or a proxy URL string.", "oneOf": [ { "type": "object", "properties": { "server": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" } }, "required": [ "server" ] }, { "type": "string" } ] } }, "required": [ "post_url", "text", "reddit_session", "loid" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/api/reddit/v2/comment": { "post": { "operationId": "reddit-comment-v2", "summary": "Post Comment v2", "description": "Post a comment via the v2 write path. Cost: $0.012 per call.", "tags": [ "Write" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.012, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "post_url": { "type": "string", "description": "Any reddit.com post URL" }, "text": { "type": "string", "description": "Comment body (plain text)" }, "reddit_session": { "type": "string", "description": "Account session cookie (from /api/reddit/login)" }, "loid": { "type": "string", "description": "Account loid cookie (from /api/reddit/login)" }, "token_v2": { "type": "string", "description": "Reddit token_v2 cookie" }, "csrf_token": { "type": "string", "description": "Reddit CSRF token cookie" }, "edgebucket": { "type": "string", "description": "edgebucket cookie" }, "csv": { "type": "string", "description": "csv cookie" }, "session_tracker": { "type": "string", "description": "session_tracker cookie" } }, "required": [ "post_url", "text", "reddit_session", "loid" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/api/reddit/vote": { "post": { "operationId": "reddit-vote", "summary": "Vote", "description": "Cast or clear an up/down vote on a post or comment. Cost: $0.005 per call.", "tags": [ "Write" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.005, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "thing_id": { "type": "string", "description": "t3_xxx for a post, t1_xxx for a comment" }, "direction": { "type": "string", "description": "up | down | none (clear existing vote)" }, "reddit_session": { "type": "string", "description": "Account session cookie (from /api/reddit/login)" }, "loid": { "type": "string", "description": "Account loid cookie (from /api/reddit/login)" }, "token_v2": { "type": "string", "description": "Reddit token_v2 cookie" }, "csrf_token": { "type": "string", "description": "Reddit CSRF token cookie" }, "edgebucket": { "type": "string", "description": "edgebucket cookie" }, "csv": { "type": "string", "description": "csv cookie" }, "session_tracker": { "type": "string", "description": "session_tracker cookie" } }, "required": [ "thing_id", "direction", "reddit_session", "loid", "csrf_token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/api/reddit/profile/description": { "post": { "operationId": "reddit-profile-description", "summary": "Update Bio", "description": "Update the logged-in account's profile bio (publicDescription). Plain text, up to 200 characters. Cost: $0.012 per call.", "tags": [ "Profile" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.012, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "description": { "type": "string", "maxLength": 200, "description": "New bio — plain text, <= 200 chars" }, "reddit_session": { "type": "string", "description": "Account session cookie (from /api/reddit/login)" }, "csrf_token": { "type": "string", "description": "Reddit CSRF token cookie" }, "loid": { "type": "string", "description": "Account loid cookie (from /api/reddit/login)" }, "token_v2": { "type": "string", "description": "Reddit token_v2 cookie" }, "edgebucket": { "type": "string", "description": "edgebucket cookie" }, "csv": { "type": "string", "description": "csv cookie" }, "session_tracker": { "type": "string", "description": "session_tracker cookie" }, "proxy": { "description": "Sticky IP for this account — match the proxy used for /api/reddit/login. Object { server, username?, password? } or a proxy URL string.", "oneOf": [ { "type": "object", "properties": { "server": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" } }, "required": [ "server" ] }, { "type": "string" } ] }, "max_attempts": { "type": "integer", "default": 3, "description": "Retry budget (default 3)" } }, "required": [ "description", "reddit_session", "csrf_token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/api/reddit/profile/display-name": { "post": { "operationId": "reddit-profile-display-name", "summary": "Set Display Name", "description": "Set the profile display name (the human-readable name shown above the username). Does not change the username. Up to 90 characters. Cost: $0.012 per call.", "tags": [ "Profile" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.012, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "display_name": { "type": "string", "maxLength": 90, "description": "New display name, <= 90 chars" }, "reddit_session": { "type": "string", "description": "Account session cookie (from /api/reddit/login)" }, "csrf_token": { "type": "string", "description": "Reddit CSRF token cookie" }, "loid": { "type": "string", "description": "Account loid cookie (from /api/reddit/login)" }, "proxy": { "description": "Sticky IP for this account — match the proxy used for /api/reddit/login. Object { server, username?, password? } or a proxy URL string.", "oneOf": [ { "type": "object", "properties": { "server": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" } }, "required": [ "server" ] }, { "type": "string" } ] }, "max_attempts": { "type": "integer", "default": 3, "description": "Retry budget (default 3)" } }, "required": [ "display_name", "reddit_session", "csrf_token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/api/reddit/profile/avatar": { "post": { "operationId": "reddit-profile-avatar", "summary": "Upload Avatar / Banner", "description": "Upload a new avatar or banner for the logged-in account. Provide the image via URL, base64, or a server-local path (PNG/JPEG, auto-detected). Provide exactly one of image_url, image_base64, or image_path. Cost: $0.012 per call.", "tags": [ "Profile" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.012, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "image_url": { "type": "string", "description": "Publicly-fetchable image URL — the server downloads it" }, "image_base64": { "type": "string", "description": "Base64-encoded image (with or without data:image/...;base64, prefix)" }, "image_path": { "type": "string", "description": "Server-local path (rarely useful)" }, "kind": { "type": "string", "description": "avatar (default) or banner" }, "mimetype": { "type": "string", "description": "Hint (PNG / JPG) — auto-detected from bytes if omitted" }, "filename": { "type": "string", "description": "Filename to record (default avatar.png)" }, "reddit_session": { "type": "string", "description": "Account session cookie (from /api/reddit/login)" }, "csrf_token": { "type": "string", "description": "Reddit CSRF token cookie" }, "loid": { "type": "string", "description": "Account loid cookie (from /api/reddit/login)" }, "proxy": { "description": "Sticky IP for this account — match the proxy used for /api/reddit/login. Object { server, username?, password? } or a proxy URL string.", "oneOf": [ { "type": "object", "properties": { "server": { "type": "string" }, "username": { "type": "string" }, "password": { "type": "string" } }, "required": [ "server" ] }, { "type": "string" } ] }, "max_attempts": { "type": "integer", "default": 3, "description": "Retry budget (default 3)" } }, "required": [ "reddit_session", "csrf_token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/api/reddit/dm": { "post": { "operationId": "reddit-dm-send", "summary": "Send DM", "description": "Send a direct message to a user. Provide either to_username or to_user_t2. Cost: $0.025 per call.", "tags": [ "Direct Messages" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.025, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to_username": { "type": "string", "description": "Target username (resolved to t2_xxx). Provide this OR to_user_t2." }, "to_user_t2": { "type": "string", "description": "Target t2_xxx ID directly (skips username lookup, ~300ms faster)." }, "message": { "type": "string", "description": "Plain-text DM body" }, "reddit_session": { "type": "string", "description": "Account session cookie (from /api/reddit/login)" }, "loid": { "type": "string", "description": "Account loid cookie (from /api/reddit/login)" }, "csrf_token": { "type": "string", "description": "Reddit CSRF token cookie" } }, "required": [ "message", "reddit_session", "loid", "csrf_token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/api/reddit/dm/threads": { "post": { "operationId": "reddit-dm-threads", "summary": "List DM Threads", "description": "List the logged-in account's DM threads. Cost: $0.025 per call.", "tags": [ "Direct Messages" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.025, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reddit_session": { "type": "string", "description": "Account session cookie (from /api/reddit/login)" }, "loid": { "type": "string", "description": "Account loid cookie (from /api/reddit/login)" }, "csrf_token": { "type": "string", "description": "Reddit CSRF token cookie" } }, "required": [ "reddit_session", "loid", "csrf_token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/api/reddit/dm/messages": { "post": { "operationId": "reddit-dm-messages", "summary": "Fetch Messages", "description": "Fetch the messages of a single DM thread. Cost: $0.025 per call.", "tags": [ "Direct Messages" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0.025, "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "room_id": { "type": "string", "description": "Thread ID from /api/reddit/dm/threads (e.g. !hdsti...:reddit.com)" }, "limit": { "type": "integer", "default": 50, "maximum": 100, "description": "Messages per page (default 50, max 100)" }, "before": { "type": "string", "description": "Cursor from a previous response's next_cursor. Omit for the first (latest) page." }, "reddit_session": { "type": "string", "description": "Account session cookie (from /api/reddit/login)" }, "loid": { "type": "string", "description": "Account loid cookie (from /api/reddit/login)" }, "csrf_token": { "type": "string", "description": "Reddit CSRF token cookie" } }, "required": [ "room_id", "reddit_session", "loid", "csrf_token" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" }, "502": { "$ref": "#/components/responses/UpstreamError" } } } }, "/account/me": { "get": { "operationId": "account-me", "summary": "My Account", "description": "Get your account info, current balance, and usage summary. Free — does not consume credits. Rate-limited to 30 requests/minute per API key. Cost: Free per call.", "tags": [ "Account" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/account/payments": { "get": { "operationId": "account-payments", "summary": "Payment History", "description": "List your account's payment / top-up history. Free — does not consume credits. Cost: Free per call.", "tags": [ "Account" ], "security": [ { "bearerAuth": [] } ], "x-cost-usd": 0, "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Pass your API key as a bearer token on every request: Authorization: Bearer ." } }, "schemas": { "Error": { "type": "object", "description": "Error response envelope.", "properties": { "error": { "type": "string", "description": "Human-readable error message." } } } }, "responses": { "BadRequest": { "description": "Bad request — missing or invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Invalid Bearer token.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServerError": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "UpstreamError": { "description": "Upstream (Reddit) rejected the request — cookies expired or account flagged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }