Snuze

Unofficial Reddit API Reference

This document attempts to describe certain data exposed by Reddit's API. The information here was compiled by observing API responses, examining Reddit's old public source code, reviewing some threads in /r/redditdev, and a bit of guesswork. Corrections to inaccurate information are welcome, just make a post in /r/snuze.

Subreddit - About

The fields described here are returned by the /r/subreddit/about API endpoint.

In Snuze, this entity is represented by the \snuze\Reddit\Thing\Subreddit class.

"thing" kind

A subreddit has a "thing" kind of t5. Subreddit entity fullnames begin with t5_.

Data structure

The JSON for this entity returned by the Reddit API server is structured as follows:

{
   "kind": "t5",
   "data": {
       "field_name": "value",
       ...
   }
}

Fields

All fields are not necessarily exposed for every subreddit. Fields that either don't apply to, or haven't been configured for, a given subreddit are frequently omitted from the JSON.

accounts_active, accounts_active_is_fuzzed, active_user_count, advertiser_category, all_original_content, allow_discovery, allow_images, allow_videogifs, allow_videos, banner_background_color, banner_background_image, banner_img, banner_size, can_assign_link_flair, can_assign_user_flair, coins, collapse_deleted_comments, collections_enabled, comment_score_hide_mins, community_icon, content_category, created, created_utc, description, description_html, disable_contributor_requests, display_name, display_name_prefixed, emojis_custom_size, emojis_enabled, event_posts_enabled, free_form_reports, has_menu_widget, header_img, header_size, header_title, hide_ads, icon_img, icon_size, id, is_crosspostable_subreddit, is_enrolled_in_new_modmail, key_color, lang, link_flair_enabled, link_flair_position, mobile_banner_image, name, notification_level, original_content_tag_enabled, over18, primary_color, public_description, public_description_html, public_traffic, quarantine, restrict_commenting, restrict_posting, show_media, show_media_preview, spoilers_enabled, submission_type, submit_link_label, submit_text, submit_text_html, submit_text_label, subreddit_type, subscribers, suggested_comment_sort, title, url, user_can_flair_in_sr, user_flair_background_color, user_flair_css_class, user_flair_enabled_in_sr, user_flair_position, user_flair_richtext, user_flair_template_id, user_flair_text, user_flair_text_color, user_flair_type, user_has_favorited, user_is_banned, user_is_contributor, user_is_moderator, user_is_muted, user_is_subscriber, user_sr_flair_enabled, user_sr_theme_enabled, videostream_links_count, whitelist_status, wiki_enabled, wls

accounts_active

integer, or empty array

The (approximate) number of users interacting with this subreddit over the past 15 minutes. This value may be "fuzzed" (see accounts_active_is_fuzzed).

Reddit occasionally returns an empty array instead of an integer. This isn't reproducible. I suspect this boils down either to cache failures, or that generating this value is an expensive operation which is sometimes abandoned.

This field is a duplicate of active_user_count.

accounts_active_is_fuzzed

bool

For subreddits with a low number of subscribers, Reddit will artificially inflate the active user count in order to mitigate statistical inference attacks.

active_user_count

integer, or empty array

The (approximate) number of users interacting with this subreddit over the past 15 minutes. This value may be "fuzzed" (see accounts_active_is_fuzzed).

Reddit occasionally returns an empty array instead of an integer. This isn't reproducible. I suspect this boils down either to cache failures, or that generating this value is an expensive operation which is sometimes abandoned.

This field is a duplicate of accounts_active.

advertiser_category

string

The advertiser categeory this subreddit falls under, if any has been assigned. If no value has been assigned, an empty string is returned.

Observed values (as of August 2019) include: Automotive, Business / Finance, College / University, Entertainment, Family & Youth, Games, Health, Lifestyles, Local, Retail, Sports, Technology, Travel

all_original_content

bool

Whether or not this subreddit has the "mark all posts in this subreddit as Original Content (OC) on the desktop redesign" option enabled.

allow_discovery

bool

Whether or not this subreddit has the "allow this subreddit to be exposed to users who have shown intent or interest through discovery and onboarding" option enabled.

allow_images

bool

Whether or not this subreddit has the "allow image uploads and links to image hosting sites" option enabled.

allow_videogifs

bool

Unknown. A videogif sounds like something from the 2400 baud days...

allow_videos

bool

Whether or not this subreddit has the "allow video uploads" option enabled.

banner_background_color

string

The HTML hex color code for this subreddit's banner background color, if one has been set. If no value has been assigned, an empty string is returned.

banner_background_image

string

The URL to this subreddit's banner background image, if any. This is the banner that displays on the desktop site. If no value has been assigned, an empty string is returned.

banner_img

string

The URL to this subreddit's banner background image, if any. This is the banner that displays on the mobile site. If no value has been assigned, an empty string is returned.

banner_size

array or null

If banner_img is set, this will be an array containing two integer elements that define the image's width and height, e.g. [1280,384]. If no banner image is configured, this will be null.

bool

Whether or not users can assign flair to their own links in this subreddit. If false, only a moderator can assign flair to links.

can_assign_user_flair

bool

Whether or not this subreddit allows users to assign flair to themselves. If false, only a moderator can assign flair to users.

coins

integer

This subreddit's Community Awards coin balance. If the subreddit has no Community Awards coins, this will be 0.

This is a moderator-only property. To receive an accurate value, the API user must be a moderator of the subreddit, and must be authenticated to the API with a valid access token. Other users will receive a 0 value.

collapse_deleted_comments

bool

Whether or not this subreddit has the "collapse deleted and removed comments" option enabled.

collections_enabled

bool

Whether or not this subreddit supports collections. A collection is a special type of self-post which allows for the aggregation of other links.

comment_score_hide_mins

integer

The "Minutes to hide comment scores" value configured for this subreddit.

community_icon

string

The URL to this subreddit's community icon image, if any has been configured. If no value has been assigned, an empty string is returned.

content_category

string

The content category assigned to this subreddit, if any has been configured. If no value has been assigned, an empty string is returned.

Observed values (as of August 2019) include: animals, diy_and_crafts, drawing_and_painting, entertainment, food, funny, gaming, memes, music, photography, videos, writing

created

float

The unix epoch timestamp at which this subreddit was created. This is provided as a float, but the fractional part is always zero.

This epoch value, and not created_utc, is the one used to display the subreddit's creation time when hovering over "a community for..." in its sidebar.

created_utc

float

The unix epoch timestamp reflecting the point 8 hours later than created. This is provided as a float, but the fractional part is always zero.

This value will always be 8 hours ahead of (i.e. 28800 greater than) the value of created. At any given second, the unix epoch is the same all around the world; this was probably intended to track the variance between Pacific time and UTC, but it's unclear whether or not it's used.

description

string

A description of this subreddit as supplied by its moderator(s).

In the legacy web interface, this is the text from the "sidebar" field in the subreddit settings editor; it gets displayed in the legacy sidebar. This field is not displayed in the redesign web interface.

description_html

string or null

The contents of description converted to HTML entities. If no description has been configured, this will be null.

disable_contributor_requests

bool

Whether or not this subreddit has the "Accepting new requests to post" option turned off. This is intended for subreddits with a subreddit_type of restricted.

display_name

string

The base name of the subreddit with no decorators or adornments, e.g. funny.

display_name_prefixed

string

The name of the subreddit prefixed with its relative URI path, e.g. r/funny, or u/joe for user profile subreddits.

emojis_custom_size

array or null

If "Custom sized emojis" has been configured for this subreddit, this will be an array containing two integer elements that define the emoji width and height, e.g. [16,16]. If no custom emoji size is configured, this will be null.

emojis_enabled

bool

Whether or not this subreddit has the "Enable emojis in this community" option enabled.

event_posts_enabled

bool

Whether or not this subreddit allows event posts, which include scheduling information, to be submitted.

free_form_reports

bool

Whether or not this subreddit has the "allow free-form reports by users" option enabled. If the option is disabled, users must choose from a list of canned reporting reasons.

has_menu_widget

bool

Whether or not this subreddit has custom menu tabs (submenu or link tabs) defined in the redesign web interface.

header_img

string or null

The URL to this subreddit's custom header image, if any. In the legacy web interface, this is the image that would appear in place of the default Snoo. If no custom header image is configured, this will be null.

header_size

array or null

If a header_img has been configured for this subreddit, this will be an array containing two integer elements that define the image's width and height, e.g. [16,16]. If no header image is configured, this will be null.

header_title

string or null

The title configured for this subreddit's header_img, if any. This is used on the legacy web interface as the <img alt=""> text for the custom header image. If no header title is configured, this will be null. This field may be populated even if header_img is null, as an artifact from that field being previously set.

hide_ads

bool

Whether or not ads have been administratively suppressed in this subreddit.

icon_img

string

The URL to this subreddit's icon image, if any. In the redesign web interface, this icon is displayed in the "Community Details" portion of the sidebar, and on site listings (e.g. front page, /r/all) when the card layout is selected. If no icon image is configured, an empty string is returned.

icon_size

array or null

If an icon_img has been configured for this subreddit, this will be an array containing two integer elements that define the image's width and height, e.g. [256,256]. If no icon image is configured, this will be null.

id

string

The base36 internal Reddit identifier for this subreddit, e.g. 2qpqw.

is_crosspostable_subreddit

bool or null

Whether or not this subreddit has the "Allow crossposting of posts" preference enabled. If crossposting is disabled, this will be null instead of false.

is_enrolled_in_new_modmail

bool or null

Whether or not this subreddit has enrolled in the new-style modmail interface. Newly created subreddits are automatically enrolled as of ~2018.

This is a moderator-only property. To receive an accurate value, the API user must be a moderator of the subreddit, and must be authenticated to the API with a valid access token. Other users will receive a null value.

key_color

string

The HTML hex color code for this subreddit's general theme color, if any is set. This corresponds to the "used as a thematic color for your subreddit on mobile" subreddit option. If no color is configured, an empty string is returned.

lang

string

The language/localization setting for this subreddit, if any. If no language is configured, an empty string is returned.

Observed values (as of August 2019) include: af, ar, bg, bs, ca, cs, da, de, el, en, eo, es, et, fa, fi, fr, gd, gl, he, hi, hr, hu, hy, id, is, it, ja, ko, la, lt, lv, nl, nn, no, pl, pt, pt-pt, ro, ru, sk, sl, sr, sv, ta, th, tr, uk, vi, zh

bool

Whether or not link flair is enabled in this subreddit.

string

The CSS position of a link's flair in this subreddit, relative to the link, i.e. left or right. If link flair is not configured, an empty string is returned.

mobile_banner_image

string

The URL to this subreddit's mobile banner image. If no mobile banner is configured, an empty string is returned.

name

string

The fullname identifier of this subreddit. This is a combination of the thing kind (t5) and the id, separated by an underscore, e.g. t5_2qh38

notification_level

string or null

Unknown. Observed values (as of August 2019) include: low

This is a moderator-only property. To receive an accurate value, the API user must be a moderator of the subreddit, and must be authenticated to the API with a valid access token. Other users will receive a null value.

original_content_tag_enabled

bool

Whether or not this subreddit has the "enable marking posts as Original Content (OC) on the desktop redesign" option enabled.

over18

bool

Whether or not this subreddit has the "viewers must be over eighteen years old" option enabled.

primary_color

string

The HTML hex color code for this subreddit's primary color, if any. This corresponds to the "Base" theme color in the redesign web interface. If a color is not configured, an empty string is returned.

public_description

string

A description of this subreddit, as supplied by its moderator(s). If none has been configured, an empty string is returned.

In the legacy web interface, this is the public-facing description that gets displayed external to the subreddit; for example, in subreddit search results. In the redesign web interface, this text is displayed in the "Community Details" portion of the sidebar. In both the legacy and redesign web interfaces, this text is used to build the <meta name="description"> tag.

public_description_html

string

The contents of public_description converted to HTML entities. If no public description has been configured, an empty string is returned.

public_traffic

bool

Whether or not this subreddit exposes its traffic statistics to the public.

quarantine

bool

Whether or not this subreddit is quarantined.

This is a restricted property. To access a quarantined subreddit through this endpoint, the API user must have affirmatively clicked "continue" on its quarantine interstitial page at some point, and must be authenticated to the API with a valid access token. Other users will receive a 403 error when attempting to access a quarantined subreddit.

restrict_commenting

bool

Unknown

restrict_posting

bool

Whether or not submitting new links is restricted in this subreddit. This will be true when subreddit_type is restricted.

show_media

bool

Whether or not this subreddit has the "show thumbnail images of content" option enabled.

show_media_preview

bool

Whether or not this subreddit has the "expand media previews on comments pages" option enabled.

spoilers_enabled

bool

Whether or not this subreddit allows tagging submissions as spoilers.

submission_type

string

The type of links that can be submitted in this subreddit. This will typically be one of any, link, or self; some banned and employee-only subreddits have this value set to an empty string.

string or null

The text configured for this subreddit's "Custom label for submit link button" option, if any. If no text has been configured, this will be null.

submit_text

string

This subreddit's configured "text to show on submission page," if any. If text is not configured, an empty string is returned.

submit_text_html

string

The contents of submit_text converted to HTML entities. If no text has been configured, this will be null.

submit_text_label

string or null

The text configured for this subreddit's "Custom label for submit text post button" option, if any. If no text has been configured, this will be null.

subreddit_type

string

The access level applied to this subreddit. This will be one of public, restricted, private, or employees_only.

This is a restricted property. To receive an accurate value for subreddits with a type other than public or restricted, the API user must have access to the subreddit, and must be authenticated to the API with a valid access token. Other users will receive a 403 error when attempting to access a private or employees_only subreddit.

subscribers

integer

The number of accounts subscribed to this subreddit.

suggested_comment_sort

string or null

The suggested comment sort order for this subreddit, if one has been set. If no sort order has been configured, this will be null.

Observed values (as of August 2019) include: confidence, controversial, live, new, old, qa, random, top

title

string

The title of this subreddit.

url

string

The fully-qualified relative URI path to this subreddit, e.g. /r/HotPeppers, or /u/joe for user profile subreddits.

user_can_flair_in_sr

bool or null

Whether or not the API user is allowed to set user flair in this subreddit. This will be true if the "Allow users to assign their own" user flair option is enabled, or if the API user is a moderator of this subreddit with the "flair" permission. If neither of these conditions are satisfied, this will be null.

user_flair_background_color

string or null

The HTML hex code of the API user's flair background color in this subreddit, if any. If the API user has no flair, or no background color is defined, this will be null.

user_flair_css_class

string or null

The CSS class corresponding to the API user's flair in this subreddit, if any. If the API user has no flair, or no CSS class is defined, this will be null.

user_flair_enabled_in_sr

bool

Whether or not user flair is enabled in this subreddit. This applies to the subreddit generally, not to the individual API user.

user_flair_position

string

The CSS position of user flair in this subreddit, relative to the username, i.e. left or right. If user flair is not configured, an empty string is returned.

user_flair_richtext

array

If the API user has user flair in this subreddit, and its user_flair_type is richtext, this will be an array containing two string elements which define the user's flair. The first element, named e, contains the string text. The second element, named t, contains the literal string that comprises the user's flair. For example,

[{"e":"text","t":"Proud Shitposter"}]

user_flair_template_id

string or null

If the API user has user flair in this subreddit, and the user flair has been chosen from a predefined template, this will contain the 36-character UUID of the template. If user flair is not configured, or is an ad-hoc string with no predefined template, this will be null.

user_flair_text

string or null

If the API user has user flair in this subreddit, this will contain the literal string that comprises the user's flair. If user flair is not configured, this will be null.

user_flair_text_color

string or null

If the API user has user flair in this subreddit, this will contain a contrast label for their flair text, either light or dark. If user flair is not configured, this will be null.

user_flair_type

string

If the API user has user flair in this subreddit, this will contain the flair type, either text or richtext. If user flair is not configured, this defaults to text.

user_has_favorited

bool

Whether or not the API user has added this subreddit to their favorites list from its "Community Details" sidebar widget.

user_is_banned

bool

Whether or not the API user is banned from participating in this subreddit.

user_is_contributor

bool

Whether or not the API user has been explicitly added as an approved user in this subreddit.

user_is_moderator

bool

Whether or not the API user is a moderator of this subreddit.

user_is_muted

bool

Whether or not the API user has been muted in this subreddit.

user_is_subscriber

bool

Whether or not the API user has subscribed to this subreddit.

user_sr_flair_enabled

bool or null

Whether or not the API user has opted to display their user flair in this subreddit ("Show my flair on this subreddit. It looks like..." in the legacy interface; "Show my user flair on this community" in the redesign interface). This may be null if the API user has no user flair or has not indicated a display preference for it.

user_sr_theme_enabled

bool

Whether or not the API user allows this subreddit to display custom CSS (legacy terminology) or a community theme (redesign terminology) via the "allow subreddits to show me custom themes" preference.

integer or null

Unknown. If set, the value appears to max out at 100.

whitelist_status

string

The advertising whitelist status of this subreddit, if set. If no whitelist status has been configured, an empty string is returned.

Observed values (as of August 2019) include: all_ads, house_only, promo_adult_nsfw, promo_all, no_ads

wiki_enabled

bool or null

Whether or not the API user has access to edit this subreddit's wiki. This will be true if one or more of the following conditions is satisfied:

  • The wiki is set to be editable by "anyone," or
  • The wiki is set to "disabled" and the API user is a moderator, or
  • The wiki is set to "mod editing" and the API user is either a moderator or an approved contributor

Otherwise, this will be null.

wls

integer

A numeric value corresponding to the whitelist_status.