These are the methods of the Reddit::Client class.

Terminology

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, i.e. t1_3npkj4). To avoid confusion, this guide will always refer to things in the following way:

Term Description Example
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

Listings

Methods that return lists of things can accept several optional parameters:

Parameter Type Description
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. Only relevant to listings that could contain both.
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.

Misc

approve

approve ( $fullname )

Approve a comment or post (moderator action).

ban

ban ( username => $username, subreddit => $subreddit,
    [ duration => $duration, ] [ ban_message => $message, ] [ reason => $reason, ] [ note => $note ] )

Ban a user from a subreddit. username and subreddit are required. Optional arguments include:

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.

comment

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

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.

The remaining arguments don't currently do anything. It seems like at least some of them are intended for future mobile updates.

delete

delete ( $fullname )

Delete a post or comment.

delete_multi

delete_multi ( $multireddit_name )

Delete a multireddit.

edit

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_multi

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

edit_wiki ( subreddit => $subreddit, page => $page, content => $content,
          [ previous => $previous_version_id, ] [ reason => $edit_reason, ] )

find_subreddits

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_collapsed_comments

get_collapsed_comments ( link_id => $link_id, children => $children,
                       [ limit_children => 0, ] [ sort => $sort, ] )

Expand a list of collapsed comments found in a MoreComments object. Return a flat list of Comment objects.

link_id is the ID of the link the comments are under. children is a reference to an array containing the comment IDs.

If limit_children is true, return only the requested comments, not replies to them. Otherwise return as many replies as possible (possibly resulting in more MoreComments objects down the line). sort is one of 'confidence', 'top', 'new', 'controversial', 'old', 'random', 'qa', 'live'. Default seems to be 'confidence'.

get_comment

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.

You can get its replies at the same time by setting include_children to a true value, at the cost of making a second request.

get_comments

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 )

or

get_comments ( permalink => $permalink )

or

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. This is analogous 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 function, which takes no arguments and supplies all of the necessary information for you. If you do decide to use this version:

Interally, all of these options simply create a permalink and pass it on to Reddit's API, because that is the only argument that Reddit's API accepts.

get_flair_options

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:

get_inbox

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 $id_or_fullname.

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_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.

Here is an explanation of the mode options from the API site:

num_reports has the total number of reports. Reports themselves can be found in the mod_reports and 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_modqueue

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_multi

get_multi ( name => $multi_name, 
          [ user => $username, ] [ expand => 0, ] )

Get a hash of information about a multireddit. $username defaults to your 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.

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 and $post_id can be either fullnames or short IDs.

get_refresh_token

Reddit::Client->get_refresh_token ( $code, $redirect_uri, $client_id, $secret, $user_agent )

Get a permanent refresh token for use in Web-type apps. All arguments are required*. Returns the refresh token.

This is best called in static context, just as it's written above (i.e. with Reddit::Client->get_refresh_token, 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.)

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.

get_subreddit_comments

get_subreddit_comments ( [ subreddit => '', ] )

Returns a list of Comment objects from a subreddit or multi. Can accept any of the listings arguments.

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). sub can be used as an alias for subreddit.

get_subreddit_info

get_subreddit_info ( $subreddit )

Returns a hash of information about subreddit $subreddit.

get_token

get_token ( client_id => $client_id, secret => $secret, username => $username, password => $password )

or

get_token ( client_id => $client_id, secret => $secret, refresh_token => $refresh_token )

or

get_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. Similarly, 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

get_user ( user => $username, [ view => USER_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 or Comments or a mix of both, except in the case of the 'about' view, in which case it will be a single Account object.

get_wiki

get_wiki ( sub => $subreddit, page => $page, 
         [ data => 0, ] [ v => $version, ] [ v2 => $diff_version ] )

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.

get_wiki_data

get_wiki_data ( sub => $subreddit, page => $page, 
              [ v => $version, ] [ v2 => $diff_version ] )

Get a data hash for wiki page $page. This function is the same as calling get_wiki with data=>1.

has_token

has_token()

Return true if a valid Oauth token exists.

hide

hide ( $fullname )

Hide a post.

ignore_reports

ignore_reports ( $fullname )

Ignore reports for a comment or post (moderator action).

info

info ( $fullname )

Returns a hash of information about $fullname. $fullname can be any of the 8 types of thing.

list_subreddits

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: home (the default, which is actually an empty string), 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.

mark_inbox_read

mark_inbox_read()

Mark everything in your inbox as read. May take some time to complete.

me

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.

new

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 ] )

or

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 ] )

Instantiate a new Reddit::Client object. Optionally authenticate at the same time. (Unless you have some reason not to, this is the simplest 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).

Debug options:

remove

remove ( $fullname )

Remove a post or comment (as a moderator). Link and Comment objects also have their own remove method, which doesn't require a fullname.

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

save

save ( $fullname )

Save a post or comment.

send_message

send_message ( to => $username, subject => $subject, text => $message )

Send a private message to $username. $subject is limited to 100 characters.

set_post_flair

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

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

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_crosspost

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.

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.

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".) sub can be used as an alias for subreddit.

submit_text

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. sub can be used as an alias for subreddit.

unhide

unhide ( $fullname )

Unhide a post.

unsave

unsave ( $fullname )

Unsave a post or comment.

version

version()

Return the Reddit::Client version.

vote

vote ( $fullname, $direction )

Vote on a post or comment. Direction must be 1, 0, or -1 (0 to clear votes).