Reddit::Client - A Perl wrapper for the Reddit API.
Reddit::Client handles Oauth session management and HTTP communication with Reddit's external API. For more information about the Reddit API, see https://github.com/reddit/reddit/wiki/API.
1.395 02/17/2023
use Reddit::Client; # Create a Reddit::Client object and authorize: "script"-type app my $reddit = new Reddit::Client( user_agent => "Test script 1.0 by /u/myusername", client_id => "client_id_string", secret => "secret_string", username => "reddit_username", password => "reddit_password", ); # Create a Reddit::Client object and authorize: "web"-type app # Authorization can also be done separately with get_token() my $reddit = new Reddit::Client( user_agent => "Test script 1.0 by /u/myusername", client_id => "client_id_string", secret => "secret_string", refresh_token => "refresh_token", ); # Check your inbox my $me = $reddit->me(); print "You've got mail!" if $me->{has_mail}; # Submit a link $reddit->submit_link( subreddit => "test", title => "Change is bad, use Perl", url => "http://www.perl.org", ); # Get posts from a subreddit or multi my $posts = $reddit->get_links(subreddit=>'test', limit=>5); for my $post (@$posts) { print $post->{is_self} ? $post->{selftext} : $post->{url}; print $post->get_web_url(); if ($post->{title} =~ /some phrase/) { $post->reply("hi, I'm a bot, oops I'm banned already, harsh"); } }
Reddit::Client uses Oauth to communicate with Reddit. To get Oauth keys, visit your apps page on Reddit, located at https://www.reddit.com/prefs/apps, and create an app. There are three types of apps available. Reddit::Client supports "script" and "web" type apps.
Most new users will want a "script"-type app. This is an app intended for personal use that uses a username and password to authenticate. The description and about url fields can be empty, and the redirect URI can be any valid URL (script apps don't use them). Once created, you can give other users permission to use it by adding them in the "add developer" field. Each account uses its own username and password to authenticate.
Use the app's client id and secret along with your username and password to create a new Reddit::Client object.
As of v1.20, Reddit::Client also supports "web"-type apps. These are apps that can take actions on behalf of any user that grants them permission. (They use the familiar "ThisRedditApp wants your permission to..." screen.)
While they are fully supported, there is not yet a setup guide, so getting one running is left as an exercise for the reader. You will need a web server, which you will use to direct users to Reddit's authorization page, where the user will be asked to grant the app permissions. Reddit's authorization page will then redirect the user back to the app's redirect URI. This process generates a refresh token, which is a unique string that your app will use to authenticate instead of a username and password. You will probably want to store refresh tokens locally, otherwise you will have to get permission from the user every time the app runs.
Documentation for the web app flow can be found at https://github.com/reddit-archive/reddit/wiki/OAuth2.
v1 is "old" Reddit (the one you see if you use the subdomain old.reddit.com), v2 new (the one you see with new.reddit.com). Reddit's API has some endpoints that are for one or the other.
If a function has multiple versions, use v2 unless you have a reason not to. It's usually the same as v1 but with more options, like flair, which can have extra colors and styles in New Reddit (and some listing pages outside of subreddits in Old Reddit).
Reddit's API is slightly inconsistent in its naming. To avoid confusion, this guide will always use the following terms in the following ways:
A thing's short ID without prefix. Example: 3npkj4. Seen in your address bar when viewing, for example, a post or comment.
A thing's complete ID with prefix. Example: t1_3npkj4. When Reddit returns data, the fullname is usually found in the "name" field. The type of thing can be determined by the prefix; for example, t1 for comments and t3 for links.
Lists of things returned by the Reddit API are called listings. Endpoints that return listings accept several optional parameters:
limit: Integer. How many things to return. Default 25, maximum 100. If limit is 0, this is interpreted as "no limit" and the maximum is returned.
limit
after: Fullname. Return results that occur after fullname in the listing.
after
before: Fullname. Return results that occur before fullname in the listing.
before
only: The string "links" or "comments". Return only links or only comments. (Only relevant to listings that could contain both.)
only
show_all: Boolean. Return items that would have been omitted, for example posts you have hidden, or have reported, or are hidden from you because you are using the option to hide posts after you've upvoted/downvoted them. Default false.
show_all
count: Integer. Appears to be used by the Reddit website to number listings after the first page. Listings returned by the API are not numbered, so it does not seem to have a use in the API.
count
Note that 'before' and 'after' mean before and after in the listing, not necessarily in time. It's best to think of Reddit as a database where new lines are constantly inserted at the top, because that's basically what it is.
Most functions that take the parameter subreddit also accept the alias sub, likewise for username and user.
subreddit
sub
username
user
Optional arguments are indicated by a hard-coded default value:
function ( $required, $optional = 'default_value' )
Most methods accept options as a hash after normal arguments (and sometimes in place of normal arguments). These may be provided as an actual hash, or with key => value shorthand.
key => value
function ( $required, %options ) # as an actual hash function ( $required, option2 => 'default_value' ) # with hash shorthand
Required options are indicated as a scalar.
function ( option1 => $is_required, option2 => 'is_optional' )
approve ( $fullname )
Approve a comment or post (moderator action).
approve_user ( $username, $subreddit, $unapprove = 0 )
Add an approved user to a subreddit (moderator action). Set $unapprove to un-approve (also available with alias unapprove_user($user, $subreddit)).
unapprove_user($user, $subreddit)
Replaces deprecated function add_approved_user.
ban ( username => $username, subreddit => $subreddit, duration => 0, ban_message => undef, reason => undef, note => undef )
Ban a user from a subreddit. username and subreddit are required. Optional arguments:
duration: Duration in days. Range 1-999. If false or not provided, the ban is indefinite.
duration
ban_message: The message sent to the banned user. Markdown is allowed.
ban_message
reason: A short ban reason, 100 characters max. On the website ban page, this in equivalent to the ban reason you would select from the dropdown menu. (For example, "Spam".) It is arbitrary: it doesn't have to match up with the reasons from the menu and can be blank. Only visible to moderators.
reason
note: An optional note, 300 characters max. Only visible to moderators. Will be concatenated to the `reason` on the subreddit's ban page.
note
A ban will overwrite any existing ban for that user. For example, to change the duration, you can call ban() again with a new duration.
ban()
comment ( $fullname, $text )
Make a comment under $fullname, which must be a post or a comment. Return the fullname of the new comment.
$fullname
create_multi ( name => $multi_name, description => undef, visibility => 'private', subreddits => [ ], icon_name => undef, key_color => 'CEE3F8', weighting_scheme => undef, username => undef )
Create a multireddit. The only required argument is the name. A multi can also be created with edit_multi, the only difference being that create_multi will fail with a HTTP 409 error if a multi with that name already exists. As of March 2019, trying to add a banned sub to a multi will fail with a 403 Unauthorized.
edit_multi
create_multi
Requires a username, which script apps have by default, but if you're using a web app, you'll need to either pass it in explicitly, or set the username property on your Reddit::Client object.
Returns a hash of information about the newly created multireddit.
name The name of the multireddit. Maximum 50 characters. Only letters, numbers and underscores are allowed (and underscores cannot be the first character). Required.
name
description Description of the multi. This can contain markdown.
description
visibility One of 'private', 'public', or 'hidden'. Default 'private'.
visibility
subreddits or subs: An array reference.
subreddits
subs
The remaining arguments don't currently do anything. It seems like at least some of them are intended for future mobile updates.
icon_name: If provided, must be one of the following values: 'art and design', 'ask', 'books', 'business', 'cars', 'comics', 'cute animals', 'diy', 'entertainment', 'food and drink', 'funny', 'games', 'grooming', 'health', 'life advice', 'military', 'models pinup', 'music', 'news', 'philosophy', 'pictures and gifs', 'science', 'shopping', 'sports', 'style', 'tech', 'travel', 'unusual stories', 'video', '', 'None'.
icon_name
weighting_scheme: If provided, must be either 'classic' or 'fresh'.
weighting_scheme
key_color: A 6-character hex code. Defaults to CEE3F8.
key_color
delete ( $fullname )
Delete a post or comment.
delete_multi ( $multireddit_name )
Delete a multireddit.
distinguish ( $fullname, sticky => 0, how => 'yes' )
Distinguish a comment or post (moderator action). Options:
sticky Distinguish and sticky a comment. Only works for top-level comments.
sticky
how This option should probably be left untouched. Valid values are "yes", "no", "admin", "special". Admin is for Reddit admins only; the rest are unexplained.
how
duplicates ( $post_id, subreddit => $subreddit, sort => 'num_comments', crossposts_only => 0 )
Show all the posts on Reddit that share the URL of the target post. Returns a listing of Links. Corresponds to the "other discussions" tab on the Reddit website. Also accepts all the arguments other listings do (before, after, etc).
Optional arguments that are specific to this function:
subreddit: Return only matches from this subreddit.
crossposts_only: Boolean, default false. Return only crossposts.
crossposts_only
sort: A string, either 'num_comments' or 'new'. Default 'num_comments'.
sort
There is nothing preventing you from using it on a text post, but it will return no results.
edit ( $fullname, $text )
Edit a text post or comment. Unlike on the website, $text can be an empty string. (It must be defined but can be a false value.)
$text
Edit a multireddit. Will create a new multireddit if one with that name doesn't exist. The arguments are identical to create_multi.
edit_wiki ( subreddit => $subreddit, page => $page, content => '', previous => undef, reason => undef )
Create or edit a wiki page. subreddit and page are required. Optional:
content is the new page content. Can be empty but must be defined. Maximum 524,288 characters.
content
reason is the edit reason. Max 256 characters, will be truncated if longer. Optional.
previous is the ID of the intended previous version of the page; if provided, that is the version the page will be rolled back to in a rollback. However, there's no way to find out what this should be from the Reddit website, or currently from Reddit::Client either. Use it only if you know what you're doing.
previous
Note that if you are updating your sub's automod (which you can do using the page "config/automoderator"), and it has syntax errors, it will fail with the message "HTTP 415 Unsupported Media Type".
find_subreddits ( q => $query, sort => 'relevance' )
Returns a list of Subreddit objects matching the search string $query. Optionally sort them by sort, which can be "relevance" or "activity".
$query
flair_link ( subreddit => $subreddit, link_id => $link_id_or_fullname, text => undef, css_class => undef )
Flair a post with arbitrary text and css class.
text and css_class are optional. If not provided, they will remove the existing text and/or css class. One advantage of doing this through the API (as opposed to the Reddit website) is that a css class can be applied with no text at all, not even an empty string. This allows you to have automoderator react to a thread or user in ways that are almost invisible to users. (They could see the CSS class if they were to inspect the proper element on the website).
text
css_class
css_class can be anything; it does not have to match an existing flair template. To select a flair template from the sub's list of flair, use select_post_flair.
text will be truncated to 64 characters if longer.
Alias for flair_link.
flair_user ( username => $username, subreddit => $sub, css_class => undef, text => undef )
Flair a user with arbitrary text and css class. Behaves exactly as flair_post except that it is given a username instead of a link ID. To select a flair template from the sub's list of flair, use select_flair.
flairtemplate( subreddit => $subreddit, allowable_content => 'all', background_color => undef, flair_template_id => undef, flair_type => 'LINK_FLAIR', text => undef, text_color => undef, text_editable => 1, max_emojis => undef, mod_only => 0, override_css => undef )
Create or edit a v2 flair template. The new flair can be used from the old (v1) interface; the V2 options will simply not be present.
Every argument except subreddit is optional. If you supply flair_template_id, it will edit the flair with that id, otherwise it will create a new one.
flair_template_id
subreddit: Required. Accepts alias 'sub'.
allowable_content: "all", "emoji", or "text". Default all.
allowable_content
background_color: 6 digit hex code, with or without a hash mark.
background_color
flair_template_id or id: Accepts alias 'id'.
id
flair_type: 'LINK_FLAIR' or 'USER_FLAIR'. Defaults to LINK_FLAIR (this differs from the API, which defaults to URER_FLAIR).
flair_type
max_emojis: An integer from 1 to 10, default 10.
max_emojis
mod_only: Whether it can be edited by non-moderators. Default false.
mod_only
text: A string up to 64 characters long.
text_color: 'dark' or 'light'. Default dark. To prevent confusion that this option might want an actual color, Reddit::Client will die with an error if given any other value.
text_color
text_editable: Whether the flair's text is editable. Default true.
text_editable
override_css: This has no documentation and preliminary tests haven't shown it to do anything. In certain cases, Reddit's V2 flair style will override V1 flair CSS, for example when applied by Automod; it may be intended to control this behavior.
override_css
Reddit will return a hash reference with some information about the new or edited flair. The returned keys do not match the input keys in all cases, unfortunately.
get_comment ( $id_or_fullname, include_children => 0 )
Returns a Comment object for $id_or_fullname. Note that by default, this only includes the comment itself and not replies. This is by Reddit's design; there isn't a way to return a comment and its replies in one request, using only the comment's id.
$id_or_fullname
You can get its replies at the same time by setting include_children to a true value, which will cause Reddit::Client to make a second request before getting back to you.
include_children
get_comments ( subreddit => $subreddit, link_id => $link_id_or_fullname )
or
get_comments ( subreddit => $subreddit, link_id => $link_id_or_fullname, comment_id => $comment_id_or_fullname )
get_comments ( permalink => $permalink )
get_comments ( url => $url )
Get the comment tree for the selected subreddit/link_id, subreddit/link_id/comment_id, permalink, or URL. This will be a mix of Comment and MoreComments objects, which are placeholders for collapsed comments. They correspond to the "show more comments" links on the website.
If you already have a Link or Comment object, it's best to call its own get_comments method, which takes no arguments and supplies all of the necessary information for you. If you do decide to use this version:
get_comments
permalink is the value found in the permalink field of a Link or Comment. It is the URL minus the protocol and hostname, i.e. "/r/subreddit/comments/link_id/optional_title/comment_id". This is somewhat awkward but it's just how Reddit works. It's not intended to be something you contruct yourself; this option is intended for passing in the permalink from an existing Link or Comment.
permalink
url is a complete URL for a link or comment, as seen in address bar on the website.
url
subreddit, link_id and comment_id should be self explanatory. It accepts either short IDs or fullnames, and like all functions that take subreddit as an argument, it can be appreviated to sub.
link_id
comment_id
Internally, all of these options simply create a permalink and pass it on to Reddit's API, because that is the only argument that this endpoint accepts.
MoreComments
When iterating a list of Comments (for example from get_comments), you may come across objects with type "more". They correspond to the comments on the website that are not initially expanded (you have to click "show more comments" to see them). It is a MoreComments object. Use its get_collapsed_comments method to get a list of the Comments it contains.
my $cmts = $r->get_comments( url => $url ); for my $cmt ( @$cmts ) { if ( $cmt->type eq 'more' ) { print "This is a MoreComments object. Expanding children.\n"; my $more = $cmt->get_collapsed_comments(); # $more is now an array reference containing Comments and possibly more MoreComments } }
This example shows the functionality but is not very useful, because each MoreComment may contain even more MoreComments, which themselves may contain even more MoreComments. That means to get at every last comment, you need a recursive function or similar.
get_flair_options( subreddit => $subreddit, link_id => $link_id_or_fullname ) get_flair_options( subreddit => $subreddit, username => $username )
Get the link or user's current flair, and options for flair that may be applied. Return flair options for the post or the user provided. Returns a hash containing two keys:
choices is an array of hash references containing the flair options. Most important is flair_template_id, which is used to set the flair of a post or user with set_post_flair or set_user_flair. flair_text contains the text of the flair.
choices
flair_text
current is a hash of the post or user's existing flair.
current
This endpoint seems to be the only way to retrieve a link or user's current flair template ID.
To get a link or user's v2 flair list, which includes values like background color and text color (but does not include the current flair template ID), use get_link_flair_options or get_user_flair_options.
get_inbox ( view => 'inbox' )
Returns a listing of Message objects, where view is one of the MESSAGE constants. All arguments are optional. If all are omitted your default inbox will be returned-- what you would see if you went to reddit.com and clicked the mailbox icon.
view
Checking your inbox via the API doesn't mark it as read. To do that you'll need to call mark_inbox_read.
mark_inbox_read
get_link ( $id_or_fullname )
Returns a Link object for $id_or_fullname.
get_link_flair_options ( $subreddit )
Get a list of the subreddit's link flairs. Uses the V2 endpoint, which includes values like background color and text color. (The V1 endpoint is still available through get_link_flair_options_v1, however its return values are a subset of the V2 options so there is not much reason to use it.)
get_links ( subreddit => undef, view => VIEW_DEFAULT )
Returns a listing of Link objects. All arguments are optional.
subreddit can be a subreddit or multi (ex: "pics+funny"). If omitted, results from the user's front page will be returned-- i.e. what you would see if you visited reddit.com as that user.
fetch_links() is an alias for get_links().
fetch_links()
get_links()
get_links_by_id ( @ids_or_fullnames )
Return an array of Link objects.
get_modlinks ( subreddit => 'mod', mode => 'modqueue' )
Return links related to subreddit moderation. subreddit defaults to 'mod', which is subreddits you moderate. mode can be one of 5 values: reports, spam, modqueue, unmoderated, and edited. It defaults to 'modqueue'. Using both defaults will get you the same result as clicking the "modqueue" link that RES places in the upper left of the page, or /r/mod/about/modqueue.
mode
Here is an explanation of the mode options from the API site:
reports: Things that have been reported.
spam: Things that have been marked as spam or otherwise removed.
modqueue: Things requiring moderator review, such as reported things and items caught by the spam filter. Default.
unmoderated: Things that have yet to be approved/removed by a mod.
edited: Things that have been edited recently.
num_reports contains the total number of reports. Reports themselves can be found in the mod_reports and user_reports properties. These are arrays of arrays, i.e.
num_reports
mod_reports
user_reports
[ [ "Spam", 3 ], [ "report #2", 1 ] ] # user_reports [ [ "mod report", "moderator_name" ] ] # mod_reports
The number with user_reports is the number of times that particular report has been sent. This is mainly for duplicates that users have selected from the menu, for example "Spam".
get_modqueue ( subreddit => 'mod' )
Get the modqueue, i.e. the listing of links and comments you get by visiting /r/mod/about/modqueue. Optionally supply a subreddit. Defaults to 'mod', which is all subreddits you moderate. Identical to calling get_modlinks (subreddit = 'mod', mode => 'modqueue')>.
get_modlinks (subreddit =
get_multi ( name => $multi_name, user => $username, expand => 0 )
Get a hash of information about a multireddit. $username defaults to your username.
$username
If expand is true, returns more detailed information about the subreddits in the multi. This can be quite a bit of information, comparable to the amount of information contained in a Subreddit object, however it's not exactly the same, and if you try to create a Subreddit object out of it you'll fail.
expand
new_modmail_conversation ( body => $markdown, subject => $subject, subreddit => $subreddit, to => $username, hide_author => 1 )
Creates a new modmail conversation and sends the first message in it. Returns a new ModmailConversation object, which will contain the first message as a ModmailMessage object.
All keys are required except for hide_author, which defaults to true. This is different than the behavior of the Reddit website, which shows the name of the moderator by default. hide_author is an alias for isAuthorHidden, the field's proper name, which you can use instead.
Reddit's documentation incorrectly says that to should be a fullname. It is actually just a username. (A user's fullname would be something like t2_xxxxx.)
to
get_permalink ( $comment_id, $post_id )
Returns a permalink for $comment_id. If you already have a Comment object, use its get_permalink() function instead. This version causes an extra request because it has to ask Reddit for the parent post's URL first, while a Comment object already has that information. It's provided for backwards compatibility, and for the rare case when you may have a comment's ID but not a comment object (perhaps you have a list of IDs stored in a database). It may be deprecated in the future.
$comment_id
get_permalink()
$comment_id and $post_id can be either fullnames or short IDs.
$post_id
Reddit::Client->get_refresh_token ( $code, $redirect_uri, $client_id, $secret, $user_agent )
Get a permanent refresh token for use in "web" apps. All arguments are required*. Returns the refresh token.
This is best called in static context, just as it's written above, rather than by instantiating an RC object first. The reason is that it's completely separate from every other program flow and you only create extra work for yourself by using an existing RC object. If you choose to use an existing RC object, you'll need to create it and then call get_token with your new refresh_token as a parameter. (client_id and secret will need to be passed in either on object creation or when calling get_token.)
get_token
client_id
secret
code is the one-time use code returned by Reddit after a user authorizes your app. For an explanation of that and redirect_uri, see the token retrieval code flow: https://github.com/reddit-archive/reddit/wiki/OAuth2#token-retrieval-code-flow.
code
redirect_uri
get_subreddit_comments ( subreddit => undef )
Returns a list of Comment objects from a subreddit or multi. If subreddit is omitted the account's "front page" subreddits are returned (i.e. what you see when you visit reddit.com and are logged in).
get_subreddit_info ( $subreddit, $page = undef )
Returns a hash of information about subreddit $subreddit. If $page is provided, return that page.
$subreddit
$page can be one of (this list may not be complete): banned, muted, contributors, wikibanned, wikicontributors, moderators, edit (returns the subreddit's settings), log, modqueue, unmoderated, reports, edited. 'rules' and 'traffic' are accepted by Reddit but always return undefined (as of 2/15/2021). 'flair' will cause an error.
get_token ( client_id => $client_id, secret => $secret, username => $username, password => $password )
get_token ( client_id => $client_id, secret => $secret, refresh_token => $refresh_token )
Get an authentication token from Reddit. Normally a user has no reason to call this function themselves. If you pass in your authentication info when creating a new Reddit::Client onject, get_token will be called automatically using the information provided. If your script runs continuously for more than an hour, a new token will be obtained automatically. get_token is exposed in case you need to refresh your authorization token manually for some reason, for example if you want to switch to a different user within the same Reddit::Client instance.
If any arguments are provided, all of the appropriate arguments are required. If none are provided, it will use the information from the previous call.
get_user ( user => $username, view => 'overview' )
Get information about a user, where view is one of the user constants: overview, comments, submitted, gilded, upvoted, downvoted, hidden, saved, or about. Defaults to 'overview', which shows the user's most recent comments and posts.
The result will be a listing of Links and/or Comments, except in the 'about' view, in which case it will be a single Account object.
get_user_flair_options ( $subreddit )
Get a list of the subreddit's user flairs. Uses the V2 endpoint, which includes values like background color and text color. (The V1 endpoint is still available through get_user_flair_options_v1, however its return values are a subset of the V2 options so there is not much reason to use it.)
get_wiki ( sub => $subreddit, page => $page, data => 0, v => undef, v2 => undef )
Get the content of a wiki page. If data is true, fetch the full data hash for the page. If v is given, show the wiki page as it was at that version. If both v and v2 are given, show a diff of the two.
data
v
v2
get_wiki_data ( sub => $subreddit, page => $page, v => undef, v2 => undef )
Get a data hash for wiki page $page. This function is the same as calling get_wiki with data=1>.
get_wiki
data=
has_token()
Return true if a valid Oauth token exists.
hide ( $fullname )
Hide a post.
ignore_reports ( $fullname )
Ignore reports for a comment or post (moderator action).
info ( $fullname )
Returns a hash of information about $fullname. This will be the raw information hash from Reddit, not loaded into an object of the appropriate class (because classes don't exist for every type of thing, and because Reddit periodically updates the API, creating new fields, so it's nice to have a way to look at the raw data it's returning). $fullname can be any of the 8 types of thing.
list_subreddits ( view => undef )
Returns a list of subreddits, where view is one of the subreddit constants: '' (i.e. home), 'subscriber', 'popular', 'new', 'contributor', or 'moderator'. Note that as of January 2018 some views, such as the default, are limited to 5,000 results. 'new' still gives infinite results (i.e. a list of all subreddits in existence). Others are untested.
lock ( $fullname, lock => 1 )
Lock a post's comment section or individual comment (moderator action). Will fail with a 400 if used on an archived (over 6 months old) post.
Using optional argument lock => 0 is the same as calling unlock on the fullname.
lock => 0
mark_inbox_read()
Mark everything in your inbox as read. May take some time to complete.
me()
Return an Account object that contains information about the logged in account. Aside from static account information it contains the has_mail property, which will be true if there is anything in your inbox.
has_mail
mute ( username => $username, subreddit => $subreddit, [ note => $note ] )
Mute a user (moderator action). Optionally leave a note that only moderators can see.
# script-type app new ( user_agent => $user_agent, client_id => $client_id, secret => $secret, username => $username, password => $password, print_request_errors => 0, print_response => 0, print_request => 0, print_request_on_error => 0, subdomain => 'www' )
# web-type app new ( user_agent => $user_agent, client_id => $client_id, secret => $secret, refresh_token => $refresh_token, print_request_errors => 0, print_response => 0, print_request => 0, print_request_on_error => 0, subdomain => 'www', username => undef )
Instantiate a new Reddit::Client object. Optionally authenticate at the same time. (Unless you have some reason not to, this is the recommended way to do it.) For "script"-type apps, this is done by passing in a username, password, client_id and secret. For "web"-type apps, this is done by passing in a refresh_token, client_id and secret.
user_agent is a string that uniquely identifies your app. The API rules say it should be "something unique and descriptive, including the target platform, a unique application identifier, a version string, and your username as contact information". It also includes this warning: "NEVER lie about your user-agent. This includes spoofing popular browsers and spoofing other bots. We will ban liars with extreme prejudice." user_agent is required as of version 1.2 (before, Reddit::Client would provide one if you didn't).
user_agent
subdomain is the subdomain in links generated by Reddit::Client (for example with get_web_url). You can use this to generate links to old.reddit.com to force the old version of Reddit, for example, or new.reddit.com for the new. Default www.
subdomain
get_web_url
username is optional for web apps. Unlike a script app, at no point does a web app know your username unless you explicitly provide it. This means that if you're using a function that requires a username (create_multi and edit_multi are two), and you haven't either passed it into the function directly or set the property in your Reddit::Client object, it will fail.
Error handling
By default, if there is an error, Reddit::Client will print the HTTP status line and then die. You can change this behavior with the following variables:
print_request_errors: If there was an error, print some information about it before dying.
print_request_errors
Reddit will usually return some JSON in the case of an error. If it has, Reddit::Client will add some of its own information to it, encode it all to a JSON string, print it, and die. It will contain the keys code, status_line, error (which will always be 1), and data, which will contain Reddit's JSON data. The fields in Reddit's return JSON are unpredictable and vary from endpoint to endpoint.
status_line
error
Sometimes Reddit will not return valid JSON; for example, if the request fails because Reddit's CDN was unable to reach their servers, you'll get a complete webpage. If Reddit did not return valid JSON for this or some other reason, Reddit::Client will print the HTTP status line and the content portion of the response.
print_response_content: Print the content portion of Reddit's HTTP response.
print_response_content
print_request: Print the entire HTTP request and response.
print_request
print_request_on_error: If there is a request error, print the entire HTTP request and response.
print_request_on_error
nsfw ( $fullname, nsfw => 1 )
Flag a post as NSFW (moderator action).
Using optional argument nsfw => 0 is the same as calling unnsfw on the fullname.
nsfw => 0
remove ( $fullname )
Remove a post or comment (moderator action). Link and Comment objects also have their own remove method, which doesn't require a fullname.
remove
Note on the mechanics of Reddit: removing is different than flagging as spam, although both have the end result of hiding a thing from view of non-moderators. Flagging as spam also trains the spam filter and will cause further posts from that user to be automatically removed.
save ( $fullname )
Save a post or comment.
send_message ( to => $username, subject => $subject, text => $message )
Send a private message to $username. $subject is limited to 100 characters.
$subject
select_flair ( link_id => $id_or_fullname, subreddit => $subreddit, flair_id => $flair_template_id, background_color => 'cccccc', css_class => '', text_color => 'dark', text => '' )
select_flair ( username => $username, subreddit => $subreddit, flair_id => $flair_template_id, background_color => 'cccccc', css_class=> '', text_color => 'dark', text => '' )
Select flair for a user or link from among the sub's flair templates. To flair a post without an existing template, use flair_post (v1 only).
background_color Hex code, with or without hash mark. Defaults to light grey.
css_class The CSS class to be used in the v1 interface. No effect on v2 interface.
flair_template_id is acquired via get_link_flair_options or get_user_flair_options. It can also be copied from the v2 flair interface on the website. flair_id may be used as an alias for flair_template_id. Required.
flair_id
link_id The link to apply flair to. Either it or username is required.
return_rtjson all|only|none. "all" saves attributes and returns json (default), "only" only returns json, "none" only saves attributes.
return_rtjson
subreddit The subreddit.
text The flair text. 64 characters max.
text_color The text color on the v2 interface. Can be "dark" (default) or "light". To help prevent mistaking this option for an actual color, select_flair will die with an error if given anything else.
username Username to apply flair to. Either it or link_id is required.
Deprecated. Use select_flair (v2) or flair_post (v1).
Deprecated. Use select_flair (v2) or flair_user (v1).
submit_comment ( parent_id => $fullname, text => $text)
Deprecated in favor of comment. Submit a comment under $fullname, which must be a post or comment. Returns fullname of the new comment.
submit_crosspost ( subreddit => $subreddit, title => $title, source_id => $fullname, inbox_replies => 1, repost => 0 )
Submit a crosspost. Returns the fullname of the new post.
source_id is the id or fullname of an existing post. This function is identical to submit_link, but with source_id replacing url.
source_id
submit_link
If inbox_replies is defined and is false, disable inbox replies for that post. If repost is true, the link is allowed to be a repost. (Otherwise, if it is a repost, the request will fail with the error "That link has already been submitted".) sub can be used as an alias for subreddit.
inbox_replies
repost
submit_link ( subreddit => $subreddit, title => $title, url => $url, [ inbox_replies => 1, ] [ repost => 0, ] [ nsfw => 0, ] )
Submit a link. Returns the fullname of the new post.
submit_text ( subreddit => $subreddit, title => $title, [ text => $text, inbox_replies => 1 ] )
Submit a text post. Returns the fullname of the new post. If inbox_replies is defined and is false, disable inbox replies for that post.
unapprove_user ( $username, $subreddit )
Alias for approve_user with the $unapprove arg set (arg 3).
unban ( username => $username, subreddit => $subreddit )
Un-ban a user (moderator action).
undistinguish ( $fullname )
Un-distinguish a comment or post (moderator action).
unhide ( $fullname )
Unhide a post.
unlock ( $fullname )
Unlock a post's comment section or individual comment (moderator action).
Equivalent to calling lock($fullname, lock=>0).
lock=>0
unmute ( username => $username, subreddit => $subreddit )
Un-mute a user (moderator action).
unnsfw ( $fullname )
Remove the NSFW flag from a post (moderator action). Equivalent to calling nsfw($fullname, nsfw=>0).
nsfw=>0
unsave ( $fullname )
Unsave a post or comment.
version()
Return the Reddit::Client version.
vote ( $fullname, $direction )
Vote on a post or comment. $direction can be 1, 0, or -1 (0 to clear votes).
$direction
DEFAULT_LIMIT => 25 VIEW_HOT => '' VIEW_NEW => 'new' VIEW_CONTROVERSIAL => 'controversial' VIEW_TOP => 'top' VIEW_RISING => 'rising' VIEW_DEFAULT => VIEW_HOT VOTE_UP => 1 VOTE_DOWN => -1 VOTE_NONE => 0 SUBMIT_LINK => 'link' SUBMIT_SELF => 'self' SUBMIT_MESSAGE => 'message' SUBMIT_CROSSPOST => 'crosspost' MESSAGES_INBOX => 'inbox' MESSAGES_UNREAD => 'unread' MESSAGES_SENT => 'sent' MESSAGES_MESSAGES => 'messages' MESSAGES_COMMENTREPLIES => 'comments' MESSAGES_POSTREPLIES => 'selfreply' MESSAGES_MENTIONS => 'mentions' SUBREDDITS_HOME => '' SUBREDDITS_MINE => 'subscriber' SUBREDDITS_POPULAR => 'popular' SUBREDDITS_NEW => 'new' SUBREDDITS_CONTRIB => 'contributor' SUBREDDITS_MOD => 'moderator' USER_OVERVIEW => 'overview' USER_COMMENTS => 'comments' USER_SUBMITTED => 'submitted' USER_GILDED => 'gilded' USER_UPVOTED => 'upvoted' USER_DOWNVOTED => 'downvoted' USER_HIDDEN => 'hidden' USER_SAVED => 'saved' USER_ABOUT => 'about'
mailto:earthtone.rc@gmail.com
BSD license
To install Reddit::Client, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Reddit::Client
CPAN shell
perl -MCPAN -e shell install Reddit::Client
For more information on module installation, please visit the detailed CPAN module installation guide.