Reddit API

Schedule Reddit text and link posts with RelayAPI, including one media URL as a link, subreddit targeting, and flair support.

Quick Reference

Before You Start

Quick Start

Post to a subreddit:

import Relay from '@relayapi/sdk';

const client = new Relay();

const post = await client.posts.create({
  content: 'Tips for learning a new programming language\n\n1. Start with the official tutorial\n2. Build a small project immediately\n3. Read other people\'s code',
  targets: ['reddit'],
  scheduled_at: 'now',
  target_options: {
    reddit: {
      subreddit: 'learnprogramming'
    }
  }
});

console.log(post.id); // post_abc123

Content Types

Text/Self Post

The first line of content becomes the title, and the rest becomes the body. Reddit Markdown is supported in the body text.

const post = await client.posts.create({
  content: 'Tips for learning a new programming language\n\n1. Start with the official tutorial\n2. Build a small project immediately\n3. Read other people\'s code',
  targets: ['reddit'],
  scheduled_at: 'now',
  target_options: {
    reddit: {
      subreddit: 'learnprogramming'
    }
  }
});

Link Post

Share a URL. The title is the first line of content, and the url field creates a link post instead of a text post.

const post = await client.posts.create({
  content: 'Interesting article about modern API design patterns',
  targets: ['reddit'],
  scheduled_at: 'now',
  target_options: {
    reddit: {
      subreddit: 'programming',
      url: 'https://example.com/api-design-article'
    }
  }
});

Media URL as a Link Post

Supplying one media item creates a Reddit link post whose URL is that media item's public URL. RelayAPI does not upload the bytes to Reddit, so this is not a native Reddit image/video upload.

const post = await client.posts.create({
  content: 'Check out this view from my hike!',
  targets: ['reddit'],
  media: [
    { url: 'https://cdn.example.com/hiking-photo.jpg', type: 'image' }
  ],
  scheduled_at: 'now',
  target_options: {
    reddit: {
      subreddit: 'hiking'
    }
  }
});

Multiple Media URLs (Unsupported)

The following multi-image shape is an example of a request RelayAPI rejects. The current publisher does not call Reddit's gallery/media-upload APIs; use a single public URL or create the native gallery outside RelayAPI.

const post = await client.posts.create({
  content: 'My weekend woodworking project - start to finish',
  targets: ['reddit'],
  media: [
    { url: 'https://cdn.example.com/step1.jpg', type: 'image' },
    { url: 'https://cdn.example.com/step2.jpg', type: 'image' },
    { url: 'https://cdn.example.com/finished.jpg', type: 'image' }
  ],
  scheduled_at: 'now',
  target_options: {
    reddit: {
      subreddit: 'woodworking'
    }
  }
});

Post with Flair

Many subreddits require flair on every post. You can list available flairs for a subreddit via the RelayAPI accounts endpoint.

const post = await client.posts.create({
  content: 'What is your favorite programming language?',
  targets: ['reddit'],
  scheduled_at: 'now',
  target_options: {
    reddit: {
      subreddit: 'socialmedia',
      flair_id: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890'
    }
  }
});

Media Requirements

Media links

Native uploads

target_options Fields

All fields go inside target_options.reddit on your post request.

Published edits and voting

RelayAPI can edit the self-text of an already-published Reddit target or owned comment and can upvote, downvote, or clear_vote on a provider post. Titles, linked URLs, and media cannot be edited. These operations require the edit or vote OAuth grant, so reconnect an older account that lacks them. See Published Edits and Social Actions.

Native Reddit image, video, and gallery upload remains intentionally deferred; the publishing adapter still submits at most one public media URL as a link post.

Auto-Retry Behavior

RelayAPI automatically retries failed Reddit posts in certain scenarios:

• Link post in text-only subreddit — automatically retries as a text/self post with the URL included in the body.
• Missing required flair — automatically tries the first available flair for the subreddit.

Common Errors

Known Quirks

• Title is permanent — the post title cannot be edited after posting. Double-check before submitting.
• No native media upload — RelayAPI submits one public image/video URL as a link post.
• Each subreddit has unique, independent rules — moderation varies wildly between communities.
• New accounts are heavily restricted — karma requirements and account age gates apply.
• Reddit Markdown supported in body text for formatting.
• Gallery requests are rejected — the current RelayAPI publisher does not invoke Reddit's gallery upload flow.
• Auto-retry behavior — link posts that fail in text-only subreddits are automatically retried as self posts.
• Flair auto-retry — if flair is required but not provided, RelayAPI tries the first available flair.

Automations

Triggers

Send nodes

Base: https://oauth.reddit.com. All endpoints expect form-encoded bodies + a custom User-Agent.