These are the methods of the Reddit::Client class.
Reddit's API is slightly inconsistent in its naming; "id" sometimes refers to a thing's short ID (i.e. 3npkj4), and sometimes to its fullname (the combination of its prefix and id). To avoid confusion, this guide will always refer to things in the following way:
|fullname||A thing's complete ID with prefix. The type of thing can be determined by the first two characters ("t1" for comment, "t3" for post, etc).||t1_cvp5afk|
|id||A thing's short ID without prefix. Seen in your address bar when viewing, for example, a post or comment. Useful for constructing URLs.||3npkj4|
Methods that return lists of things can accept several optional parameters:
|limit||integer||How many things to return. Default 25, maximum 100. If limit is present but false, this is interpreted as "no limit" and the maximum is returned.|
|before||fullname||Return results that occur before fullname in the listing.|
|after||fullname||Return results that occur after fullname in the listing.|
|count||integer||Appears to be used by Reddit to number listings after the first page. Does not seem to have a use in the API.|
|only||"links" or "comments"||Return only links or comments.|
|show_all||boolean||Return items that would have been omitted, for example posts you have hidden, or were hidden because you are using the option to hide posts after you've upvoted/downvoted them. Default false.|
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.
comment ( $fullname, $text )
Make a comment under
$fullname, which must be either a post or a comment. Return the fullname of the new comment.
This function is an alias for
submit_comment, and is equivalent to
submit_comment ( parent_id => $fullname, text => $text )
create_multi ( name => $multi_name, [ description => $description, ] [ visibility => $visibility, ] [ subreddits => [ subreddits ], ] [ icon_name => $icon_name, ] [ key_color => $hex_code, ] [ weighting_scheme => $weighting_scheme, ] )
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.
Returns a hash of information about the newly created multireddit.
nameThe name of the multireddit. Maximum 50 characters. Only letters, numbers and underscores are allowed. Required.
descriptionDescription of the multi. This can contain markdown.
visibilityOne of 'private', 'public', or 'hidden'. Default 'private'.
subs: An array reference.
The remaining arguments don't currently do anything. It seems like at least some of them are intended for future mobile updates.
icon_nameIf 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'.
weighting_schemeIf provided, must be either 'classic' or 'fresh'.
key_colorA 6-character hex code. Defaults to CEE3F8.
delete ( $fullname )
Delete a post or comment.
delete_multi ( $multireddit_name )
Delete a multireddit.
edit ( $fullname, $text )
Edit a text post or comment. Unlike the website,
$text can be an empty string, although to prevent accidental wipeouts it must be defined.
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 => $content, [ previous => $previous_version_id, ] [ reason => $edit_reason, ] )
pageis the page being edited.
contentis the new page content. Can be empty but must be defined. Maximum 524,288 characters.
reasonis the edit reason. Max 256 characters, will be truncated if longer. Optional.
previousis 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.
find_subreddits ( q => $query, [ sort => 'relevance', ] [ limit => DEFAULT_LIMIT, ] [ before => undef, ] [ after => undef, ] )
Returns a list of Subreddit objects matching the search string
$query. Optionally sort them by
sort, which can be "relevance" or "activity".
get_comment ( $id_or_fullname )
Returns a Comment object for
get_flair_options( subreddit => $subreddit, post_id => $post_id_or_fullname, username => $username )
Return the flair options for either the post or the user provided.
Returns a hash containing two keys:
choicesis 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_textcontains the text of the flair.
currentis a hash of the post or user's existing flair.
get_inbox ( [ view => MESSAGES_INBOX, ] [ limit => DEFAULT_LIMIT, ] [ before => undef, ] [ after => undef, ] )
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.
Checking your inbox via the API doesn't mark it as read. To do that you'll need to call mark_inbox_read.
get_link ( $id_or_fullname )
Returns a Link object for
get_links ( [ subreddit => undef, ] [ view => VIEW_DEFAULT, ] [ limit => DEFAULT_LIMIT, ] [ before => undef, ] [ after => undef, ] )
Returns a list 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_modlinks ( [ subreddit => 'mod', ] [ mode => 'modqueue' ] )
Return a listing of unmoderated posts and comments in
subreddit defaults to 'mod', which is all 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.
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 has the total number of reports. Reports themselves can be found in the
user_reports properties. These are an array of arrays, i.e.
[ [ "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, i.e. "Spam".
get_multi ( name => $multi_name, [ user => $username, ] [ expand => 0, ] )
Get a hash of information about a multireddit.
$username defaults to your username.
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.
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.
$post_id can be either fullnames or short IDs.
get_subreddit_comments ( [ subreddit => '', ] [ limit => DEFAULT_LIMIT, ] [ before => undef, ] [ after => undef, ] )
Returns a list of Comment objects from a subreddit or multi.
All arguments are optional. 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 )
Returns a hash of information about subreddit
get_token ( client_id => $client_id, secret => $secret, username => $username, password => $password )
Get an Oauth token from Reddit. This is analogous to the old login function, and can be considered identical, with the exception that, if your script runs continuously for more than an hour, a new token will be obtained hourly.
get_user ( [ user => $username, ] [ view => USER_OVERVIEW, ] [ limit => DEFAULT_LIMIT, ][ before => undef, ] [ after => undef, ] )
Get information about a user, where
view is one of the user constants: overview, comments, submitted, gilded, upvoted, downvoted, hidden, or saved. Defaults to overview, which shows the user's most recent comments and posts.
The result can be a list of Links, Comments, or a mix of both, depending on what
view you requested. You can determine which is which by looking at the type property, which is "t1" for comments and "t3" for posts.
Return true if a valid Oauth token exists.
hide ( $fullname )
Hide a post.
info ( $fullname )
Returns a hash of information about
$fullname can be any of the 8 types of thing.
list_subreddits ( [ view => SUBREDDITS_HOME, ] [ limit => DEFAULT_LIMIT, ] [ before => undef, ] [ after => undef, ] )
Returns a list of subreddits, where
view is one of the SUBREDDIT constants.
An alias function is provided for each view type, which is the same as calling
list_subreddits() with the view already provided:
contrib_subreddits ( [ limit => DEFAULT_LIMIT, ] [ before => undef, ] [ after => undef, ] )
home_subreddits ( [ limit => DEFAULT_LIMIT, ] [ before => undef, ] [ after => undef, ] )
mod_subreddits ( [ limit => DEFAULT_LIMIT, ] [ before => undef, ] [ after => undef, ] )
my_subreddits ( [ limit => DEFAULT_LIMIT, ] [ before => undef, ] [ after => undef, ] )
new_subreddits ( [ limit => DEFAULT_LIMIT, ] [ before => undef, ] [ after => undef, ] )
popular_subreddits ( [ limit => DEFAULT_LIMIT, ] [ before => undef, ] [ after => undef, ] )
Mark everything in your inbox as read. May take some time to complete.
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.
new ( user_agent => $user_agent, [ client_id => $client_id, secret => $secret, username => $username, password => $password, ] [ request_errors => 0 ] )
Instantiate a Reddit::Client object. Optionally get an Oauth token (analogous to logging in) at the same time. If any of the four login arguments are used, all are required.
request_errors is true, display the full content of request errors. (By default it only displays the status code.)
$user_agent is always required, and should be something descriptive that uniquely identifies your app. The API Rules says 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."
save ( $fullname )
Save a post or comment.
send_message ( to => $username, subject => $subject, text => $message )
Send a private message to
$subject is limited to 100 characters.
set_post_flair ( subreddit => $subreddit, post_id => $post_id_or_fullname, flair_template_id => $flair_id )
Set the flair on a post.
flair_template_id is acquired via get_flair_options().
set_user_flair ( subreddit => $subreddit, username => $username, flair_template_id => $flair_id )
Set the flair for a user. flair_template_id is acquired via get_flair_options().
submit_comment ( parent_id => $fullname, text => $text)
Submit a comment under
$fullname, which must be a post or comment. Returns fullname of the new comment.
submit_link ( subreddit => $subreddit, title => $title, url => $url, [ inbox_replies => 1, ] [ repost => 0, ])
Submit a link. Returns the fullname of the new post. 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".)
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.
unhide ( $fullname )
Unhide a post.
unsave ( $fullname )
Unsave a post or comment.
Return the Reddit::Client version.
vote ( $fullname, $direction )
Vote on a post or comment. Direction must be 1, 0, or -1 (0 to clear votes).