Creator OS Docs: API reference, CLI, Social Agents & workflows

API resource

Posting to Reddit goes through Create a post with platforms: ["reddit"] and a reddit object (subreddit, title, flairId). These are the Reddit-only calls around it: the subreddits an account can post to, a subreddit's rules and flairs, search and feeds for research, and votes. Ids are Reddit's own.

List subreddit flairs

GET/v1/accounts/{accountId}/reddit-flairs

Works on: Reddit

Returns available post flairs for a subreddit. Some subreddits require a flair when posting.

Path parameters

accountIdstringrequired

Query parameters

subredditstringrequired

Subreddit name (without "r/" prefix) to fetch flairs for

curl "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_Rd3Kp8Vw1Nx6Ty3Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq6R/reddit-flairs?subreddit=socialmedia" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "flairs": [
    {
      "id": "string",
      "text": "string",
      "textColor": "string",
      "backgroundColor": "string"
    }
  ]
}

Set Reddit post flair

POST/v1/accounts/{accountId}/reddit-flairs

Works on: Reddit

Applies a flair to a post the connected account already published. Use the GET on this path to list the available flairTemplateId values for the subreddit. Flair can also be set at submit time by passing flairId in platformSpecificData when creating the post. This endpoint is for changing it afterwards. The subreddit must allow users to select their own post flair. Setting flair on another user's post requires moderator permissions, which Creator OS does not request.

Path parameters

accountIdstringrequired

The ID of the Reddit account that owns the post

Body

subredditstringrequired

Subreddit name (without the "r/" prefix)

postIdstringrequired

Reddit post id, with or without the t3_ prefix

flairTemplateIdstringrequired

Flair template id from the GET on this path

textstring

Optional override text, only for editable flair templates

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_Rd3Kp8Vw1Nx6Ty3Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq6R/reddit-flairs" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subreddit": "socialmedia",
    "postId": "1abcd2",
    "flairTemplateId": "string"
  }'

Response 200

{
  "success": true
}

Get subreddit rules

GET/v1/accounts/{accountId}/reddit-subreddits/{subreddit}/rules

Works on: Reddit

Returns a subreddit's posting rules plus Reddit's site-wide rules, so you can check them before submitting and avoid a removal. Use this alongside POST /v1/tools/validate/subreddit, which only confirms that a subreddit exists and reports its basic posting settings.

Path parameters

accountIdstringrequired

The ID of the Reddit account

subredditstringrequired

Subreddit name (without the "r/" prefix)

curl "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_Rd3Kp8Vw1Nx6Ty3Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq6R/reddit-subreddits/socialmedia/rules" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "rules": [
    {
      "kind": "string",
      "shortName": "string",
      "description": "string",
      "violationReason": "string",
      "createdUtc": 0,
      "priority": 0
    }
  ],
  "siteRules": [
    "string"
  ]
}

List Reddit subreddits

GET/v1/accounts/{accountId}/reddit-subreddits

Works on: Reddit

Returns the subreddits the connected Reddit account can post to. Use this to get a subreddit name when creating a Reddit post.

Path parameters

accountIdstringrequired

curl "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_Rd3Kp8Vw1Nx6Ty3Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq6R/reddit-subreddits" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "subreddits": [
    {
      "id": "string",
      "name": "string",
      "title": "string",
      "url": "string",
      "over18": true
    }
  ],
  "defaultSubreddit": "string"
}

Set default subreddit

PUT/v1/accounts/{accountId}/reddit-subreddits

Works on: Reddit

Sets the default subreddit used when publishing posts for this Reddit account.

Path parameters

accountIdstringrequired

Body

defaultSubredditstringrequired

curl -X PUT "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_Rd3Kp8Vw1Nx6Ty3Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq6R/reddit-subreddits" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "defaultSubreddit": "string"
  }'

Response 200

{
  "success": true
}

Vote on a Reddit post or comment

POST/v1/accounts/{accountId}/reddit-vote

Works on: Reddit

Cast, change, or clear the connected account's vote on a Reddit post or comment. Reddit requires that votes be cast by humans. Reddit's API terms permit a client to proxy a human's action one-for-one, and prohibit a bot from deciding how to vote or from amplifying a human's vote. Call this endpoint only in direct response to an explicit action by the account owner. Automated or agent-decided voting is vote manipulation and puts API access at risk.

Path parameters

accountIdstringrequired

The ID of the Reddit account casting the vote

Body

thingIdstringrequired

Reddit fullname of the target. Prefix "t3_" for a post and "t1_" for a comment. A bare id with no prefix is treated as a post ("t3_").

directionintegerrequired

1 to upvote, -1 to downvote, 0 to clear an existing vote

curl -X POST "https://creatoros-production-5658.up.railway.app/v1/accounts/acc_Rd3Kp8Vw1Nx6Ty3Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq6R/reddit-vote" \
  -H "Authorization: Bearer $CREATOROS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "thingId": "t3_abc123",
    "direction": 1
  }'

Response 200

{
  "success": true
}

Get the comments of a Reddit post

GET/v1/reddit/comments/{postId}

Works on: Reddit

Reads the comments of any Reddit post the connected account can see, for example one found through /v1/reddit/feed or /v1/reddit/search, straight from Reddit on every call. The tree comes flattened in thread order (a reply follows its parent); rebuild it from parentId, which is t3_… for a reply to the post and t1_… for a reply to a comment. Deleted and removed comments are passed through as Reddit sends them ([deleted] / [removed]). Where Reddit truncates a thread, the ids it left out are listed in more; commentId fetches one such comment with its replies.

Path parameters

postIdstringrequired

Reddit post id, with or without the t3_ prefix (as id or fullname on RedditPost).

Query parameters

accountIdstringrequired

An active Reddit account the request is made as.

sortstring

One of: new, top, best, controversial, old, qa.

limitinteger

Maximum number of top-level comments.

commentIdstring

Return only this comment and its replies, with or without the t1_ prefix; pass an id from more to expand it.

curl "https://creatoros-production-5658.up.railway.app/v1/reddit/comments/1abcd2?accountId=acc_Rd3Kp8Vw1Nx6Ty3Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq6R" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "post": {
    "id": "string",
    "fullname": "string",
    "title": "string",
    "author": "string",
    "subreddit": "socialmedia",
    "url": "string",
    "permalink": "string",
    "selftext": "string",
    "createdUtc": 0,
    "score": 0,
    "numComments": 0,
    "over18": true,
    "stickied": true,
    "flairText": "string",
    "isGallery": true,
    "galleryImages": [
      "string"
    ]
  },
  "items": [
    {
      "id": "string",
      "fullname": "string",
      "parentId": "string",
      "author": "string",
      "body": "string",
      "permalink": "string",
      "createdUtc": 0,
      "score": 0,
      "numReplies": 0,
      "depth": 0,
      "isSubmitter": true,
      "edited": true,
      "stickied": true,
      "distinguished": "string"
    }
  ],
  "more": [
    "string"
  ]
}

Get subreddit feed

GET/v1/reddit/feed

Works on: Reddit

Fetch posts from a subreddit feed. Supports sorting, time filtering, and cursor-based pagination.

Query parameters

accountIdstringrequired

subredditstring

sortstring

One of: hot, new, top, rising.

limitinteger

afterstring

tstring

One of: hour, day, week, month, year, all.

curl "https://creatoros-production-5658.up.railway.app/v1/reddit/feed?accountId=acc_Rd3Kp8Vw1Nx6Ty3Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq6R" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "items": [
    {
      "id": "string",
      "fullname": "string",
      "title": "string",
      "author": "string",
      "subreddit": "socialmedia",
      "url": "string",
      "permalink": "string",
      "selftext": "string",
      "createdUtc": 0,
      "score": 0,
      "numComments": 0,
      "over18": true,
      "stickied": true,
      "flairText": "string",
      "isGallery": true,
      "galleryImages": [
        "string"
      ]
    }
  ],
  "after": "string",
  "before": "string"
}

Search posts

GET/v1/reddit/search

Works on: Reddit

Search Reddit posts using a connected account. Optionally scope to a specific subreddit.

Query parameters

accountIdstringrequired

subredditstring

qstringrequired

restrict_srstring

One of: 0, 1.

sortstring

One of: relevance, hot, top, new, comments.

limitinteger

afterstring

curl "https://creatoros-production-5658.up.railway.app/v1/reddit/search?accountId=acc_Rd3Kp8Vw1Nx6Ty3Lm9Rc2Hb7Js5Df0Ga8Ue4Ki1Oq6R&q=%3Cq%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "items": [
    {
      "id": "string",
      "fullname": "string",
      "title": "string",
      "author": "string",
      "subreddit": "socialmedia",
      "url": "string",
      "permalink": "string",
      "selftext": "string",
      "createdUtc": 0,
      "score": 0,
      "numComments": 0,
      "over18": true,
      "stickied": true,
      "flairText": "string",
      "isGallery": true,
      "galleryImages": [
        "string"
      ]
    }
  ],
  "after": "string",
  "before": "string"
}

Check subreddit existence

GET/v1/tools/validate/subreddit

Works on: Reddit

Check if a subreddit exists and return basic info (title, subscriber count, NSFW status, post types allowed). When accountId is provided, uses authenticated Reddit OAuth API with automatic token refresh (recommended). Falls back to Reddit's public JSON API, which may be unreliable from server IPs. Returns exists: false for private, banned, or nonexistent subreddits.

Query parameters

namestringrequired

Subreddit name (with or without "r/" prefix)

accountIdstring

Reddit account ID for authenticated lookup (recommended for reliable results)

curl "https://creatoros-production-5658.up.railway.app/v1/tools/validate/subreddit?name=%3Cname%3E" \
  -H "Authorization: Bearer $CREATOROS_API_KEY"

Response 200

{
  "exists": true,
  "subreddit": {
    "name": "programming",
    "title": "programming",
    "description": "Computer Programming",
    "subscribers": 6844284,
    "isNSFW": true,
    "type": "public",
    "allowImages": true,
    "allowVideos": true
  }
}

PreviousMore analytics NextDiscord