Net::T...I::REST(3pm)

📦

version 4.01043 · 4 versions

4.01043 · debian bookworm, debian trixie, ubuntu noble (latest)
4.01043 · fedora 43
4.01043 · ubuntu jammy
4.01043 · ubuntu resolute

, in debian bookworm, debian trixie, ubuntu noble

✨ Net::T...I::REST (3pm) ✨

okay bestie, welcome to the Net::T...I::REST page 💖 — yes it's User Contributed Perl Documentation, and yes we are doing this. This is part 1 of 6, and we're literally starting mid-params because that's just the vibe the page woke up in today. Every param, every default, every deprecation notice, every qw/.../ list is staying exactly where it is. no cap. 🫶

🎀 params, mid-list, we're just rolling with it

status — Required. this is the actual text of your status update. URL encode it as necessary. and bestie, listen: statuses over 140 characters will cause a 403 error to come back from the API. so keep it short, keep it iconic. 😭
in_reply_to_status_id — optional. the ID of an existing status that this update is replying to. o Note: this parameter gets ignored unless the author of the tweet it references is mentioned inside the status text. so you must include @username, where username is the author of the referenced tweet, inside the update. 💅
lat — optional. the latitude this tweet refers to. valid range is -90.0 to +90.0 (North is positive), inclusive. this one gets ignored if it's outside that range, if it isn't a number, if geo_enabled is disabled, or if there's no corresponding long parameter on the same tweet. 🙈
long — optional. the longitude this tweet refers to. valid range is -180.0 to +180.0 (East is positive), inclusive. ignored if it's outside that range, if it isn't a number, if geo_enabled is disabled, or if there's no corresponding lat parameter on this tweet. 🌸
place_id — optional. the place to attach to this status update. valid place_ids can be found by querying reverse_geocode. 🗺️
display_coordinates — optional. by default, geo-tweets have their coordinates exposed in the status object (this keeps things backwards compatible with existing API applications). to turn off the display of the precise latitude and longitude — but keep the contextual location info — pass "display_coordinates =" 0> on the status update. yes that's really what it says, i don't make the rules 💀

and then the block closes out like:

EOT

);

💫 `twitter_api_method destroy_status`

this one destroys the status specified by the required ID parameter. the catch: the authenticating user must be the author of the specified status. main character only, periodt. 👑

twitter_api_method destroy_status => (
    description => <<'', Destroys the status specified by the required
ID parameter.  The authenticating user must be the author of the
specified status.

    path     => 'statuses/destroy/:id',
    method   => 'POST',
    params   => [qw/id trim_user include_entities/],
    booleans => [qw/trim_user include_entities/],
    required => [qw/id/],
    returns  => 'Status',
);

🦋 `twitter_api_method friends` — deprecated, bestie 😭

deprecated => 1, fr fr. this method has been deprecated. Twitter intends to stop support for it on May 14, 2012. use friends_ids and lookup_users instead. iykyk. 🫠

it returns a reference to an array of the user's friends. if id, user_id, or screen_name isn't specified, you get the friends of the authenticating user. the returned users are ordered from most recently followed to least recently followed. 💜

use the optional cursor parameter to retrieve users in pages of 100. when the cursor parameter is used, the return value is a reference to a hash with the keys previous_cursor, next_cursor, and users. the value of users is a reference to an array of the user's friends. the result set isn't guaranteed to be 100 every time, because suspended users get filtered out. set the optional cursor parameter to -1 to get the first page of users. set it to the prior return's value of previous_cursor or next_cursor to page forward or backwards. when there are no prior pages, previous_cursor will be 0. when there are no subsequent pages, next_cursor will be 0. ✨

it's also aliased as following, and it's the one that returns Hashref|ArrayRef[User] (lowercase ref, don't @ me).

twitter_api_method friends => (
    deprecated  => 1,
    description => <<'EOT', This method has been deprecated.  Twitter
intends to stop support for it on May 14, 2012.  Use "friends_ids" and
"lookup_users" instead.

Returns a reference to an array of the user's friends.  If "id",
"user_id", or "screen_name" is not specified, the friends of the
authenticating user are returned.  The returned users are ordered from
most recently followed to least recently followed.

Use the optional "cursor" parameter to retrieve users in pages of 100.
When the "cursor" parameter is used, the return value is a reference to
a hash with keys "previous_cursor", "next_cursor", and "users".  The
value of "users" is a reference to an array of the user's friends. The
result set isn't guaranteed to be 100 every time as suspended users will
be filtered out.  Set the optional "cursor" parameter to -1 to get the
first page of users.  Set it to the prior return's value of
"previous_cursor" or "next_cursor" to page forward or backwards.  When
there are no prior pages, the value of "previous_cursor" will be 0.
When there are no subsequent pages, the value of "next_cursor" will be
0.  EOT

    aliases  => [qw/following/],
    path     => 'statuses/friends/:id',
    method   => 'GET',
    params   => [qw/id user_id screen_name cursor include_entities/],
    booleans => [qw/include_entities/],
    required => [qw//],
    returns  => 'Hashref|ArrayRef[User]',
);

🌈 `twitter_api_method followers` — also deprecated 🥲

deprecated => 1 again. same deal: this method has been deprecated, Twitter intends to stop support for it on May 14, 2012, and you should be using friends_ids and lookup_users instead. 💀

it returns a reference to an array of the user's followers. if id, user_id, or screen_name isn't specified, the followers of the authenticating user are returned. the returned users are ordered from most recently followed to least recently followed. 🌸

the cursor situation is identical: use the optional cursor parameter to retrieve users in pages of 100. when the cursor parameter is used, the return value is a reference to a hash with keys previous_cursor, next_cursor, and users. the value of users is a reference to an array of the user's friends. the result set isn't guaranteed to be 100 every time as suspended users will be filtered out. set the optional cursor parameter to -1 to get the first page of users. set it to the prior return's value of previous_cursor or next_cursor to page forward or backwards. when there are no prior pages, previous_cursor will be 0. when there are no subsequent pages, next_cursor will be 0. 🦋

heads up: this one returns HashRef|ArrayRef[User] — capital R this time, because consistency is not the vibe here.

twitter_api_method followers => (
    deprecated  => 1,
    description => <<'EOT', This method has been deprecated.  Twitter
intends to stop support for it on May 14, 2012.  Use "friends_ids" and
"lookup_users" instead.

Returns a reference to an array of the user's followers.  If "id",
"user_id", or "screen_name" is not specified, the followers of the
authenticating user are returned.  The returned users are ordered from
most recently followed to least recently followed.

Use the optional "cursor" parameter to retrieve users in pages of 100.
When the "cursor" parameter is used, the return value is a reference to
a hash with keys "previous_cursor", "next_cursor", and "users".  The
value of "users" is a reference to an array of the user's friends. The
result set isn't guaranteed to be 100 every time as suspended users will
be filtered out.  Set the optional "cursor" parameter to -1 to get the
first page of users.  Set it to the prior return's value of
"previous_cursor" or "next_cursor" to page forward or backwards.  When
there are no prior pages, the value of "previous_cursor" will be 0.
When there are no subsequent pages, the value of "next_cursor" will be
0.  EOT

    path     => 'statuses/followers/:id',
    method   => 'GET',
    params   => [qw/id user_id screen_name cursor include_entities/],
    booleans => [qw/include_entities/],
    required => [qw//],
    returns  => 'HashRef|ArrayRef[User]',
);

👑 `twitter_api_method show_user`

returns extended information of a given user, specified by ID or screen name as per the required id parameter. this info includes design settings, so third party developers can theme their widgets according to a given user's preferences. so aesthetic of it all. 🎀 and note: you must be properly authenticated to request the page of a protected user. 🔐

twitter_api_method show_user => (
    description => <<'', Returns extended information of a given user,
specified by ID or screen name as per the required id parameter.  This
information includes design settings, so third party developers can
theme their widgets according to a given user's preferences. You must be
properly authenticated to request the page of a protected user.

    path     => 'users/show/:id',
    method   => 'GET',
    params   => [qw/id screen_name include_entities/],
    booleans => [qw/include_entities/],
    required => [qw/id/],
    returns  => 'ExtendedUser',
);

🧚 `twitter_api_method contributees`

returns an array of users that the specified user can contribute to. 💫

twitter_api_method contributees => (
    path        => 'users/contributees',
    method      => 'GET',
    params      => [qw/user_id screen_name include_entities
skip_satus/],
    required    => [],
    booleans    => [qw/include_entities skip_satus/],
    returns     => 'ArrayRef[User]',
    description => <<'', Returns an array of users that the specified
user can contribute to.

);

🍓 `twitter_api_method contributors`

returns an array of users who can contribute to the specified account. 🫶

twitter_api_method contributors => (
    path        => 'users/contributors',
    method      => 'GET',
    params      => [qw/user_id screen_name include_entities
skip_satus/],
    required    => [],
    booleans    => [qw/include_entities skip_satus/],
    returns     => 'ArrayRef[User]',
    description => <<'', Returns an array of users who can contribute to
the specified account.

);

💌 `twitter_api_method direct_messages`

returns a list of the 20 most recent direct messages sent to the authenticating user, including detailed information about the sending and recipient users. 📬

twitter_api_method direct_messages => (
    description => <<'', Returns a list of the 20 most recent direct
messages sent to the authenticating user including detailed information
about the sending and recipient users.

    path     => 'direct_messages',
    method   => 'GET',
    params   => [qw/since_id max_id count page include_entities/],
    required => [qw/include_entities/],
    returns  => 'ArrayRef[DirectMessage]',
);

📤 `twitter_api_method sent_direct_messages`

returns a list of the 20 most recent direct messages sent by the authenticating user, including detailed information about the sending and recipient users. same energy, other direction. 💌

twitter_api_method sent_direct_messages => (
    description => <<'', Returns a list of the 20 most recent direct
messages sent by the authenticating user including detailed information
about the sending and recipient users.

    path     => 'direct_messages/sent',
    method   => 'GET',
    params   => [qw/since_id max_id page count include_entities/],
    booleans => [qw/include_entities/],
    required => [qw//],
    returns  => 'ArrayRef[DirectMessage]',
);

✉️ `twitter_api_method new_direct_message`

sends a new direct message to the specified user from the authenticating user. it requires both the user and text parameters. returns the sent message when successful. 🎉 and listen — to support numeric screen names, the screen_name or user_id parameters may be used instead of user. versatile queen behavior. 👑

twitter_api_method new_direct_message => (
    description => <<'', Sends a new direct message to the specified
user from the authenticating user.  Requires both the user and text
parameters.  Returns the sent message when successful.  In order to
support numeric screen names, the "screen_name" or "user_id" parameters
may be used instead of "user".

    path     => 'direct_messages/new',
    method   => 'POST',
    params   => [qw/user text screen_name user_id include_entities/],
    booleans => [qw/include_entities/],
    required => [qw/user text/],
    returns  => 'DirectMessage',
);

💀 `twitter_api_method destroy_direct_message`

destroys the direct message specified in the required ID parameter. the authenticating user must be the recipient of the specified direct message. so you can only delete your own inbox, bestie. 🗑️

twitter_api_method destroy_direct_message => (
    description => <<'', Destroys the direct message specified in the
required ID parameter.  The authenticating user must be the recipient of
the specified direct message.

    path     => 'direct_messages/destroy/:id',
    method   => 'POST',
    params   => [qw/id include_entities/],
    booleans => [qw/include_entities/],
    required => [qw/id/],
    returns  => 'DirectMessage',
);

🔗 `twitter_api_method show_friendship`

returns detailed information about the relationship between two users. it's giving relationship status, but for the API. 💞 (also goes by show_relationship.)

twitter_api_method show_friendship => (
    description => <<'', Returns detailed information about the
relationship between two users.

    aliases  => [qw/show_relationship/],
    path     => 'friendships/show',
    method   => 'GET',
    params   => [qw/source_id source_screen_name target_id target_id_name/],
    required => [qw/id/],
    returns  => 'Relationship',
);

🫂 `twitter_api_method create_friend`

befriends the user specified in the ID parameter as the authenticating user. returns the befriended user when successful. when it's unsuccessful, it returns a string describing the failure condition. so either a whole user or a sad little string, no in-between. 😭 (aliased as follow_new.)

twitter_api_method create_friend => (
    description => <<'', Befriends the user specified in the ID
parameter as the authenticating user.  Returns the befriended user when
successful.  Returns a string describing the failure condition when
unsuccessful.

    aliases  => [qw/follow_new/],
    path     => 'friendships/create/:id',
    method   => 'POST',
    params   => [qw/id user_id screen_name follow include_entities/],
    booleans => [qw/include_entities follow/],
    required => [qw/id/],
    returns  => 'BasicUser',
);

💔 `twitter_api_method destroy_friend`

discontinues friendship with the user specified in the ID parameter as the authenticating user. returns the un-friended user when successful. when it's unsuccessful, it returns a string describing the failure condition. not the unfollow, bestie 😭 (though yes, it's aliased as unfollow.)

twitter_api_method destroy_friend => (
    description => <<'', Discontinues friendship with the user specified
in the ID parameter as the authenticating user.  Returns the un-friended
user when successful.  Returns a string describing the failure condition
when unsuccessful.

    aliases  => [qw/unfollow/],
    path     => 'friendships/destroy/:id',
    method   => 'POST',
    params   => [qw/id user_id screen_name include_entities/],
    booleans => [qw/include_entities/],
    required => [qw/id/],
    returns  => 'BasicUser',
);

🦋 `twitter_api_method friendship_exists`

tests for the existence of friendship between two users. it will return true if user_a follows user_b, otherwise it will return false. simple as that. ✨ (aliases: relationship_exists and follows.)

use of user_a and user_b is deprecated. it has been preserved for backwards compatibility, and it's used for the two-argument positional form:

$nt->friendship_exists($user_a, $user_b);

instead, you should use one of the named argument forms:

twitter_api_method friendship_exists => (
    aliases     => [qw/relationship_exists follows/], # Net::Twitter
    description => <<'EOT', Tests for the existence of friendship
between two users. Will return true if user_a follows user_b, otherwise
will return false.

Use of "user_a" and "user_b" is deprecated.  It has been preserved for
backwards compatibility, and is used for the two-argument positional
form:

    $nt->friendship_exists($user_a, $user_b);

Instead, you should use one of the named argument forms:

`friendship_exists` — the mutuals check 🫶

Not me handing you two whole ways to ask this:

$nt->friendship_exists({ user_id_a => $id1, user_id_b => $id2 });
$nt->friendship_exists({ screen_name_a => $name1, screen_name_b => $name2 });

lowkey tho, consider using show_friendship instead. 👀

path     => 'friendships/exists',
method   => 'GET',
params   => [qw/user_id_a user_id_b screen_name_a screen_name_b user_a user_b/],
required => [qw/user_a user_b/],
returns  => 'Bool',

`no_retweet_ids` 🙈

Gives you back an ARRAY ref of user IDs for which the authenticating user does not want to receive retweets. no cap.

path     => 'friendships/no_retweet_ids',
method   => 'GET',
params   => [],
required => [],
returns  => 'ArrayRef[UserIDs]',

`friends_ids` 💫

Returns a reference to an array of numeric IDs for every user followed by the specified user. Heads up bestie: the order of the IDs is reverse chronological.

Use the optional cursor parameter to retrieve IDs in pages of 5000. When the cursor parameter is used, the return value is a reference to a hash with keys previous_cursor, next_cursor, and ids. The value of ids is a reference to an array of IDS of the user's friends. Set the optional cursor parameter to -1 to get the first page of IDs. Set it to the prior return's value of previous_cursor or next_cursor to page forward or backwards. When there are no prior pages, the value of previous_cursor will be 0. When there are no subsequent pages, the value of next_cursor will be 0.

Also it has an alias, so you can call it by its other name too 🎀

aliases  => [qw/following_ids/],
path     => 'friends/ids/:id',
method   => 'GET',
params   => [qw/id user_id screen_name cursor/],
required => [qw/id/],
returns  => 'HashRef|ArrayRef[Int]',

`followers_ids` 🌸

Returns a reference to an array of numeric IDs for every user following the specified user. Fair warning: the order of the IDs may change from call to call 😭. Wanna turn those into actual names? Pass the arrayref to lookup_users.

Use the optional cursor parameter to retrieve IDs in pages of 5000. When the cursor parameter is used, the return value is a reference to a hash with keys previous_cursor, next_cursor, and ids. The value of ids is a reference to an array of IDS of the user's followers. Set the optional cursor parameter to -1 to get the first page of IDs. Set it to the prior return's value of previous_cursor or next_cursor to page forward or backwards. When there are no prior pages, the value of previous_cursor will be 0. When there are no subsequent pages, the value of next_cursor will be 0.

path     => 'followers/ids/:id',
method   => 'GET',
params   => [qw/id user_id screen_name cursor/],
required => [qw/id/],
returns  => 'HashRef|ArrayRef[Int]',

`verify_credentials` — the vibe check ✅

Returns an HTTP 200 OK response code and a representation of the requesting user if authentication was successful; returns a 401 status code and an error message if not. Basically: use this method to test if the user credentials you were handed are actually valid. iykyk.

path     => 'account/verify_credentials',
method   => 'GET',
params   => [qw/include_entities/],
booleans => [qw/include_entities/],
required => [qw//],
returns  => 'ExtendedUser',

`end_session` 👋

Ends the session of the authenticating user, returning a null cookie. Use this method to sign users out of client-facing applications like widgets. slay.

path     => 'account/end_session',
method   => 'POST',
params   => [qw//],
required => [qw//],
returns  => 'Error', # HTTP Status: 200, error content. Silly!

`update_location` 💀

deprecated alert!! This method has been deprecated in favor of the update_profile method. Its URL will continue to work, but please consider migrating to the newer and more comprehensive method of updating profile attributes.

deprecated  => 1,
path     => 'account/update_location',
method   => 'POST',
params   => [qw/location/],
required => [qw/location/],
returns  => 'BasicUser',

`update_delivery_device` 📱

Sets which device Twitter delivers updates to for the authenticating user. Send none as the device parameter and it'll disable IM or SMS updates entirely.

path     => 'account/update_delivery_device',
method   => 'POST',
params   => [qw/device/],
required => [qw/device/],
returns  => 'BasicUser',

`update_profile_colors` 🎨

Sets one or more hex values that control the color scheme of the authenticating user's profile page on twitter.com. These values are also returned in the /users/show API method. it's giving interior design honestly.

path     => 'account/update_profile_colors',
method   => 'POST',
params   => [qw/
    profile_background_color
    profile_text_color
    profile_link_color
    profile_sidebar_fill_color
    profile_sidebar_border_color
/],
required => [qw//],
returns  => 'ExtendedUser',

`update_profile_image` 🖼️

Updates the authenticating user's profile image. The image parameter is an arrayref with the following interpretation:

[ $file ]
[ $file, $filename ]
[ $file, $filename, Content_Type => $mime_type ]
[ undef, $filename, Content_Type => $mime_type, Content => $raw_image_data ]

The first value of the array ($file) is the name of a file to open. The second value ($filename) is the name given to Twitter for the file. If $filename is not provided, the basename portion of $file is used. If $mime_type is not provided, it will be provided automatically using LWP::MediaTypes::guess_media_type().

$raw_image_data can be provided, rather than opening a file, by passing undef as the first array value. obsessed with the flexibility tbh.

path     => 'account/update_profile_image',
method   => 'POST',
params   => [qw/image/],
required => [qw/image/],
returns  => 'ExtendedUser',

`update_profile_background_image` 🌈

Updates the authenticating user's profile background image. The image parameter must be an arrayref with the same interpretation as the image parameter in the update_profile_image method. The use parameter lets you specify whether to use the uploaded profile background or not. See that method's documentation for details.

path     => 'account/update_profile_background_image',
method   => 'POST',
params   => [qw/image use/],
required => [qw/image/],
booleans => [qw/use/],
returns  => 'ExtendedUser',

`rate_limit_status` ⏳

Returns the remaining number of API requests available to the authenticated user before the API limit is reached for the current hour.

Use ->rate_limit_status({ authenticate => 0 }) to force an unauthenticated call, which will return the status for the IP address rather than the authenticated user. (Note: for a web application, this is the server's IP address.) the way that actually matters for rate limits, fr fr.

path     => 'account/rate_limit_status',
method   => 'GET',
params   => [qw//],
required => [qw//],
returns  => 'RateLimitStatus',

`update_profile` 👑

Sets values that users are able to set under the Account tab of their settings page. Only the parameters specified will be updated; to only update the name attribute, for example, only include that parameter in your request. selective editing, we love to see it.

path     => 'account/update_profile',
method   => 'POST',
params   => [qw/ name email url location description include_entities/],
booleans => [qw/include_entities/],
required => [qw//],
returns  => 'ExtendedUser',

`favorites` ⭐

Returns the 20 most recent favorite statuses for the authenticating user, or for the user specified by the ID parameter.

path     => 'favorites/:id',
method   => 'GET',
params   => [qw/id page include_entities/],
booleans => [qw/include_entities/],
required => [qw//],
returns  => 'ArrayRef[Status]',

`create_favorite` 💖

Favorites the status specified in the ID parameter as the authenticating user. Returns the favorite status when successful.

path     => 'favorites/create/:id',
method   => 'POST',
params   => [qw/id include_entities/],
booleans => [qw/include_entities/],
required => [qw/id/],
returns  => 'Status',

`destroy_favorite` 💔

Un-favorites the status specified in the ID parameter as the authenticating user. Returns the un-favorited status. yes bestie, the take-back is real.

path     => 'favorites/destroy/:id',
method   => 'POST',
params   => [qw/id include_entities/],
booleans => [qw/include_entities/],
required => [qw/id/],
returns  => 'Status',

`enable_notifications` 🔔

Enables notifications for updates from the specified user to the authenticating user. Returns the specified user when successful.

path     => 'notifications/follow/:id',
method   => 'POST',
params   => [qw/id screen_name include_entities/],
booleans => [qw/include_entities/],
required => [qw/id/],
returns  => 'BasicUser',

`disable_notifications` 🔕

Disables notifications for updates from the specified user to the authenticating user. Returns the specified user when successful. main character energy: silence.

path     => 'notifications/leave/:id',
method   => 'POST',
params   => [qw/id screen_name include_entities/],
booleans => [qw/include_entities/],
required => [qw/id/],
returns  => 'BasicUser',

`create_block` 🚫

Blocks the user specified in the ID parameter as the authenticating user. Returns the blocked user when successful. You can find out more about blocking in the Twitter Support Knowledge Base.

           path     => 'blocks/create/:id',
           method   => 'POST',
           params   => [qw/id user_id screen_name include_entities/],
           booleans => [qw/include_entities/],
           required => [qw/id/],
           returns  => 'BasicUser',
       );

       twitter_api_method destroy_block => (
           description => <<'', Un-blocks the user specified in the ID
       parameter as the authenticating user.  Returns the un-blocked user when
       successful.

           path     => 'blocks/destroy/:id',
           method   => 'POST',
           params   => [qw/id user_id screen_name/],
           booleans => [qw/include_entities/],
           required => [qw/id/],
           returns  => 'BasicUser',
       );

       twitter_api_method block_exists => (
           description => <<'', Returns if the authenticating user is blocking
       a target user. Will return the blocked user's object if a block exists,
       and error with HTTP 404 response code otherwise.

           path     => 'blocks/exists/:id',
           method   => 'GET',
           params   => [qw/id user_id screen_name include_entities/],
           booleans => [qw/include_entities/],
           required => [qw/id/],
           returns  => 'BasicUser',
       );

       twitter_api_method blocking => (
           description => <<'', Returns an array of user objects that the
       authenticating user is blocking.

           path     => 'blocks/blocking',
           method   => 'GET',
           params   => [qw/page include_entities/],
           booleans => [qw/include_entities/],
           required => [qw//],
           returns  => 'ArrayRef[BasicUser]',
       );

       twitter_api_method blocking_ids => (
           description => <<'', Returns an array of numeric user ids the
       authenticating user is blocking.

           path     => 'blocks/blocking/ids',
           method   => 'GET',
           params   => [qw//],
           required => [qw//],
           returns  => 'ArrayRef[Int]',
       );

okay so blocks!!! 💅 you've got create, destroy, exists, blocking, and blocking_ids — the whole block-management situation. blocks/create/:id is the POST that makes a block happen, blocks/destroy/:id is the un-block (and it hands you back the user, all freed and everything 🕊️), blocks/exists/:id tells you whether you're blocking somebody — and lowkey if there's no block it just hits you with an HTTP 404, so brace yourself, bestie 😭. Then blocks/blocking gives you a whole array of blocked user objects (ArrayRef[BasicUser]), and blocks/blocking_ids gives you ArrayRef[Int] — just the raw numeric ids, no vibes attached. Note that include_entities is a boolean on basically all of these, and destroy_block still lists the booleans even though include_entities isn't in its params — that's just how the original wrote it, don't come for me 🫶.

       twitter_api_method test => (
           description => <<'', Returns the string "ok" status code.

           path     => 'help/test',
           method   => 'GET',
           params   => [qw//],
           required => [qw//],
           returns  => 'Str',
       );

       twitter_api_method downtime_schedule => (
           description => <<'', Returns the same text displayed on
       <http://twitter.com/home> when a maintenance window is scheduled.

           deprecated => 1,
           path     => 'help/downtime_schedule',
           method   => 'GET',
           params   => [qw//],
           required => [qw//],
           returns  => 'Str',
       );

       twitter_api_method get_configuration => (
           path        => 'help/configuration',
           method      => 'GET',
           params      => [],
           required    => [],
           returns     => 'HashRef',
           description => <<'EOT', Returns the current configuration used by
       Twitter including twitter.com slugs which are not usernames, maximum
       photo resolutions, and t.co URL lengths.

       It is recommended applications request this endpoint when they are
       loaded, but no more than once a day.  EOT

       );

       twitter_api_method get_languages => (
           path        => 'help/languages',
           method      => 'GET',
           params      => [],
           required    => [],
           returns     => 'ArrayRef[Lanugage]',
           description => <<'', Returns the list of languages supported by
       Twitter along with their ISO 639-1 code. The ISO 639-1 code is the two
       letter value to use if you include lang with any of your requests.

       );

help me help you ✨ — help/test literally just returns the string "ok" (returns 'Str', no auth, no drama, we love a simple queen). help/downtime_schedule returns the same text you'd see on http://twitter.com/home when a maintenance window is scheduled, but heads up bestie — it's marked deprecated => 1 💀.

help/configuration returns a HashRef of the current Twitter config: slugs that aren't usernames, max photo resolutions, and t.co URL lengths. And the official word is you should request it when your app loads, but no more than once a day — don't be greedy 🙈.

help/languages returns ArrayRef[Lanugage] (yes, the type name is spelled "Lanugage" in the source, iykyk, we keep it real) — the list of languages Twitter supports plus their ISO 639-1 code, which is the two-letter value you'd pass as lang in your requests. 🦋

       twitter_api_method saved_searches => (
           description => <<'', Returns the authenticated user's saved search
       queries.

           path     => 'saved_searches',
           method   => 'GET',
           params   => [],
           required => [],
           returns  => 'ArrayRef[SavedSearch]',
       );

       twitter_api_method show_saved_search => (
           description => <<'', Retrieve the data for a saved search, by "id",
       owned by the authenticating user.

           path     => 'saved_searches/show/:id',
           method   => 'GET',
           params   => [qw/id/],
           required => [qw/id/],
           returns  => 'SavedSearch',
       );

       twitter_api_method create_saved_search => (
           description => <<'', Creates a saved search for the authenticated
       user.

           path     => 'saved_searches/create',
           method   => 'POST',
           params   => [qw/query/],
           required => [qw/query/],
           returns  => 'SavedSearch',
       );

       twitter_api_method destroy_saved_search => (
           description => <<'', Destroys a saved search. The search, specified
       by "id", must be owned by the authenticating user.

           path     => 'saved_searches/destroy/:id',
           method   => 'POST',
           params   => [qw/id/],
           required => [qw/id/],
           returns  => 'SavedSearch',
       );

       twitter_api_method report_spam => (
           description => <<'', The user specified in the id is blocked by the
       authenticated user and reported as a spammer.

           path     => 'report_spam',
           method   => 'POST',
           params   => [qw/id user_id screen_name include_entities/],
           booleans => [qw/include_entities/],
           required => [qw/id/],
           returns  => 'User',
       );

saved searches are the scrapbook of your Twitter life 🎀 — saved_searches (GET) returns ArrayRef[SavedSearch] of everything the authed user has saved. saved_searches/show/:id fetches one by its id (gotta own it, no peeking at other people's stuff 👀). saved_searches/create is a POST that takes a required query and gives you back a SavedSearch. And saved_searches/destroy/:id — POST, takes id, and destroys it 💀. The search has to belong to the authenticating user though, periodt.

Then report_spam (POST) blocks the user in id and reports them as a spammer — returns a User. It takes id (required), plus optional user_id, screen_name, and the include_entities boolean. Not me having a whole arsenal for the spammers 🙈

       twitter_api_method users_search => (
           aliases     => [qw/find_people search_users/],
           path        => 'users/search',
           method      => 'GET',
           params      => [qw/q per_page page include_entities/],
           booleans    => [qw/include_entities/],
           required    => [qw/q/],
           returns     => 'ArrayRef[Users]',
           description => <<'', Run a search for users similar to Find People
       button on Twitter.com; the same results returned by people search on
       Twitter.com will be returned by using this API (about being listed in
       the People Search).  It is only possible to retrieve the first 1000
       matches from this API.

       );

       twitter_api_method trends_available => (
           path        => 'trends/available',
           method      => 'GET',
           params      => [qw/lat long/],
           required    => [],
           authenticate => 0,
           returns     => 'ArrayRef[Location]',
           description => <<EOT, Returns the locations with trending topic
       information. The response is an array of "locations" that encode the
       location's WOEID (a Yahoo!  Where On Earth ID
       <http://developer.yahoo.com/geo/geoplanet/>) and some other human-
       readable information such as a the location's canonical name and
       country.

       When the optional "lat" and "long" parameters are passed, the available
       trend locations are sorted by distance from that location, nearest to
       farthest.

       Use the WOEID returned in the location object to query trends for a
       specific location.  EOT );

users_search is the Find People button energy ✨ — it's got aliases find_people and search_users, hits users/search with GET, takes q (required!) plus per_page, page, and the include_entities boolean, and returns ArrayRef[Users]. Same results as people search on Twitter.com, and it's about being listed in the People Search. Big caveat bestie: you can only pull the first 1000 matches from this API. That's the limit, no cap 🫶

trends_available (GET, authenticate => 0, returns ArrayRef[Location]) gives you locations with trending-topic info. Each "location" encodes the location's WOEID — that's a Yahoo! Where On Earth ID, link included right there — plus other human-readable stuff like the location's canonical name and country. Pass the optional lat and long and it sorts trend locations by distance, nearest to farthest 📍. And use the WOEID from the location object to query trends for a specific spot.

       twitter_api_method trends_location => (
           path        => 'trends/:woeid',
           method      => 'GET',
           params      => [qw/woeid/],
           required    => [qw/woeid/],
           returns     => 'ArrayRef[Trend]',
           authenticate => 0,
           description => <<'', Returns the top 10 trending topics for a
       specific location. The response is an array of "trend" objects that
       encode the name of the trending topic, the query parameter that can be
       used to search for the topic on Search, and the direct URL that can be
       issued against Search.  This information is cached for five minutes, and
       therefore users are discouraged from querying these endpoints faster
       than once every five minutes.  Global trends information is also
       available from this API by using a WOEID of 1.

       );

       twitter_api_method trends => (
           description => <<'', Returns the top ten queries that are currently
       trending on Twitter.  The response includes the time of the request, the
       name of each trending topic, and the url to the Twitter Search results
       page for that topic.

           path     => 'trends',
           method   => 'GET',
           params   => [qw//],
           required => [qw//],
           authenticate => 0,
           returns  => 'ArrayRef[Query]',
           deprecated => 1,
       );

       my $trends_deprecation_warned = 0; around trends => sub {
           my $orig = shift;
           my $self = shift;

           my $args = ref $_[-1] eq ref {} ? pop : {};

           $trends_deprecation_warned ||= do {
               local $Carp::CarpLevel = 3;
               carp "The 'trends' API method has been deprecated; instead, use trends_location({ woeid => 1 })";
               1;
           };

           $args->{woeid} = 1;

           return $self->trends_location(@_, $args);
       };

trends_location (GET trends/:woeid, woeid required, authenticate => 0) serves you the top 10 trending topics for a specific location 🔥. Each "trend" object encodes the topic name, the query param you'd use to search it, and the direct URL you can hit against Search. It's cached for five minutes, so please don't query faster than once every five minutes — the manpage literally discourages it 😭. Global trends? Just use a WOEID of 1. 🌍

trends — the top ten currently-trending queries, returning ArrayRef[Query], with the request time, each topic name, and the url to the Twitter Search results page. BUT 👑 it's deprecated => 1, and there's a whole around modifier watching it: it pops your args if the last one is a hashref (ref $_[-1] eq ref {}), and the first time you call it, it carps "The 'trends' API method has been deprecated; instead, use trends_location({ woeid => 1 })" (with local $Carp::CarpLevel = 3;), and only once thanks to $trends_deprecation_warned. Then it force-sets $args->{woeid} = 1; and forwards everything to trends_location. So it still works, it's just yelling at you the whole time 💅

       twitter_api_method trends_current => (
           description => <<'', Returns the current top ten trending topics on
       Twitter.  The response includes the time of the request, the name of
       each trending topic, and query used on Twitter Search results page for
       that topic.

           path     => 'trends/current',
           method   => 'GET',
           params   => [qw/exclude/],
           required => [qw//],
           authenticate => 0,
           returns  => 'HashRef',
       );

       twitter_api_method trends_daily => (
           description => <<'', Returns the top 20 trending topics for each
       hour in a given day.

           path     => 'trends/daily',
           method   => 'GET',
           params   => [qw/date exclude/],
           required => [qw//],
           authenticate => 0,
           returns  => 'HashRef',
       );

       twitter_api_method trends_weekly => (
           description => <<'', Returns the top 30 trending topics for each day
       in a given week.

           path     => 'trends/weekly',
           method   => 'GET',
           params   => [qw/date exclude/],
           required => [qw//],
           authenticate => 0,
           returns  => 'HashRef',
       );

the trends trio 🎀 — trends/current gives the current top ten trending topics (time of request, topic names, and the query used on the Search results page), takes an exclude param, authenticate => 0, returns HashRef. trends/daily gives the top 20 topics for each hour in a given day, takes date and exclude, returns HashRef. trends/weekly gives the top 30 topics for each day in a given week, also takes date and exclude, also HashRef. All three are unauthenticated, all three are vibes. 🌈

       twitter_api_method reverse_geocode => (
           path        => 'geo/reverse_geocode',
           method      => 'GET',
           params      => [qw/lat long accuracy granularity max_results/],
           required    => [qw/lat long/],
           returns     => 'HashRef',
           description => <<'EOT',

so reverse_geocode is the where even am I endpoint 🗺️ — it searches for places (cities and neighborhoods) that can be attached to a statuses/update. Give it a latitude and a longitude and it returns a list of all the valid places usable as a place_id when updating a status. Conceptually: you query from the user's location, grab the list of places, have the user validate where they're at, then send that location's ID up with a call to statuses/update. ✨

There are multiple granularities of places that can come back — "neighborhoods", "cities", etc. And here's the important bit, bestie: at this time, only United States data is available through this method. 🇺🇸

The params it takes are lat, long, accuracy, granularity, and max_results, with lat and long being the required ones, and it returns a HashRef.

lat — Required. The latitude to query about. Valid ranges are -90.0 to +90.0 (North is positive) inclusive. 📍
long — Required. The longitude to query about. Valid ranges are -180.0 to +180.0 (East is positive) inclusive. 📍
accuracy — Optional, bestie. It's a lil hint about the "region" you're searching in. If you hand it a number, that's a radius in meters — but it can also be a string suffixed with ft to say feet. Don't pass it at all? Then it's assumed to be 0m. And if it's coming from a device, in practice this value is literally whatever accuracy that device has when measuring its own location (GPS, WiFi triangulation, whatever the vibe is). 🛰️
granularity — Optional. The minimal granularity of data to return. If you don't pass it, neighborhood is assumed. You can also pass city.
max_results — Optional. A hint about how many results to return. Heads up: this does not guarantee you'll get exactly max_results back — it just tells the API how many "nearby" results to return. Ideally you only pass in the number of places you actually intend to show the user. No cap. ✨

Then the actual method definition:

twitter_api_method geo_id => (
    path => 'geo/id/:id',
    method => 'GET',
    params => [qw/id/],
    required => [qw/id/],
    returns  => 'HashRef',
    description => <<'EOT', Returns details of a place returned from the
"reverse_geocode" method.  EOT );

So geo_id is giving "tell me everything about this one place," and the place you're asking about comes from the reverse_geocode method. It's a GET, it needs an id, and you get a HashRef back. 💖

twitter_api_method geo_search => (
    path        => 'geo/search',
    method      => 'GET',
    params      => [qw/
        lat long query ip granularity accuracy max_results
        contained_within attribute:street_address callback
    /],
    required    => [],
    returns     => 'HashRef',
    description => <<'EOT', Search for places that can be attached to a
statuses/update. Given a latitude and a longitude pair, an IP address,
or a name, this request will return a list of all the valid places that
can be used as the place_id when updating a status.

Conceptually, a query can be made from the user's location, retrieve a
list of places, have the user validate the location he or she is at, and
then send the ID of this location with a call to statuses/update.

This is the recommended method to use find places that can be attached
to statuses/update. Unlike geo/reverse_geocode which provides raw data
access, this endpoint can potentially re-order places with regards to
the user who is authenticated. This approach is also preferred for
interactive place matching with the user.  EOT

);

THIS ONE. geo_search is the recommended way to find places you can attach to statuses/update. Nothing is required (empty array, she's chill like that), and you get a HashRef back. 🗺️

The whole concept is a little flow: make a query from the user's location → get a list of places → have the user validate where they actually are → then send that location's ID along with a call to statuses/update. And unlike geo/reverse_geocode, which gives you raw data access, this endpoint can potentially re-order places with regards to who's authenticated. It's also the preferred approach for interactive place matching with the user. Obsessed. 🎀

twitter_api_method similar_places => (
    path        => 'geo/similar_places',
    method      => 'GET',
    params      => [qw/lat long name contained_within
attribute:street_address callback/],
    required    => [qw/lat long name/],
    returns     => 'HashRef',
    description => <<'EOT', Locates places near the given coordinates
which are similar in name.

Conceptually you would use this method to get a list of known places to
choose from first. Then, if the desired place doesn't exist, make a
request to "add_place" to create a new one.

The token contained in the response is the token needed to be able to
create a new place.  EOT

);

similar_places finds places near the given coordinates that have a similar name. Needs lat, long and name. Returns a HashRef.

The lore: you use this to get a list of known places to choose from first. Then if the place you want doesn't exist yet, you hit up add_place to make a new one. And the token sitting in the response? That's the token you need to actually be able to create a new place. Don't lose it, bestie. 🔑

twitter_api_method add_place => (
    path        => 'geo/place',
    method      => 'POST',
    params      => [qw/name contained_within token lat long
attribute:street_address callback/],
    required    => [qw/name contained_within token lat long/],
    returns     => 'Place',
    description => <<'EOT', Creates a new place object at the given
latitude and longitude.

Before creating a place you need to query "similar_places" with the
latitude, longitude and name of the place you wish to create. The query
will return an array of places which are similar to the one you wish to
create, and a token.  If the place you wish to create isn't in the
returned array you can use the token with this method to create a new
one.  EOT

);

add_place is a POST (it's creating something, of course it is 💅) and it makes a brand new place object at the given latitude and longitude. Returns a Place. Requires name, contained_within, token, lat, and long.

⚠️ Order matters here, fr fr: before creating a place you have to query similar_places with the latitude, longitude and name of the place you wanna create. That query gives you back an array of similar places and a token. If the place you want isn't in that returned array, then you can use the token with this method to create a new one. No skipping steps. 🚫

twitter_api_method lookup_users => (
    path => 'users/lookup',
    method => 'GET',
    params => [qw/user_id screen_name include_entities/],
    booleans => [qw/include_entities/],
    required => [],
    returns => 'ArrayRef[User]',
    description => <<'EOT' Return up to 100 users worth of extended
information, specified by either ID, screen name, or combination of the
two. The author's most recent status (if the authenticating user has
permission) will be returned inline.  This method is rate limited to
1000 calls per hour.

This method will accept user IDs or screen names as either a comma
delimited string, or as an ARRAY ref.  It will also accept arguments in
the normal HASHREF form or as a simple list of named arguments.  I.e.,
any of the following forms are acceptable:

    $nt->lookup_users({ user_id => '1234,6543,3333' });
    $nt->lookup_users(user_id => '1234,6543,3333');
    $nt->lookup_users({ user_id => [ 1234, 6543, 3333 ] });
    $nt->lookup_users({ screen_name => 'fred,barney,wilma' });
    $nt->lookup_users(screen_name => ['fred', 'barney', 'wilma']);

    $nt->lookup_users(
        screen_name => ['fred', 'barney' ],
        user_id     => '4321,6789',
    );

EOT );

lookup_users returns up to 100 users worth of extended info, specified by ID, screen name, or a combo of the two. The author's most recent status gets returned inline — but only if the authenticating user has permission. And ngl, it's rate limited to 1000 calls per hour. 🕐

The glow-up here: this method takes user IDs or screen names as either a comma-delimited string or an ARRAY ref. It'll also accept arguments in the normal HASHREF form or as a simple list of named arguments. So literally any of these forms are acceptable:

$nt->lookup_users({ user_id => '1234,6543,3333' });
$nt->lookup_users(user_id => '1234,6543,3333');
$nt->lookup_users({ user_id => [ 1234, 6543, 3333 ] });
$nt->lookup_users({ screen_name => 'fred,barney,wilma' });
$nt->lookup_users(screen_name => ['fred', 'barney', 'wilma']);

$nt->lookup_users(
    screen_name => ['fred', 'barney' ],
    user_id     => '4321,6789',
);

Flexible queen. 👑

twitter_api_method retweeted_by => (
    path => 'statuses/:id/retweeted_by',
    method => 'GET',
    params => [qw/id count page trim_user include_entities/],
    booleans => [qw/include_entities trim_user/],
    required => [qw/id/],
    returns  => 'ArrayRef[User]',
    description => <<'' Returns up to 100 users who retweeted the status
identified by "id".

);

retweeted_by returns up to 100 users who retweeted the status identified by id. Needs id, returns ArrayRef[User]. The booleans here are include_entities and trim_user.

twitter_api_method retweeted_by_ids => (
    path     => 'statuses/:id/retweeted_by/ids',
    method   => 'GET',
    params   => [qw/id count page trim_user include_entities/],
    booleans => [qw/include_entities trim_user/],
    required => [qw/id/],
    returns  => 'ArrayRef[User]',
    description => <<'' Returns the IDs of up to 100 users who retweeted
the status identified by "id".

);

Same energy, different output: retweeted_by_ids returns the IDs of up to 100 users who retweeted the status identified by id. Same params, same booleans, same required id, same ArrayRef[User] return. 🔁

twitter_api_method friendships_incoming => (
    path => 'friendships/incoming',
    method => 'GET',
    params => [qw/cursor/],
    required => [qw/cursor/],
    returns  => 'HashRef',
    description => <<'', Returns an HASH ref with an array of numeric
IDs in the "ids" element for every user who has a pending request to
follow the authenticating user.

);

friendships_incoming — requires cursor, returns a HashRef with an array of numeric IDs in the "ids" element, one for every user who has a pending request to follow the authenticating user. The requests-in-your-inbox of the Twitter world. 📥

twitter_api_method friendships_outgoing => (
    path => 'friendships/outgoing',
    method => 'GET',
    params => [qw/cursor/],
    required => [qw/cursor/],
    returns  => 'HashRef',
    description => <<'', Returns an HASH ref with an array of numeric
IDs in the "ids" element for every protected user for whom the
authenticating user has a pending follow request.

);

friendships_outgoing — same shape (needs cursor, returns HashRef), but this time it's the IDs of every protected user for whom the authenticating user has a pending follow request. The ones you sent out into the void. 🕊️

# new in 3.17001 2010-10-19

Mark the date, bestie — everything below is new in 3.17001 2010-10-19. 🗓️

twitter_api_method account_totals => (
    path        => 'account/totals',
    method      => 'GET',
    params      => [],
    required    => [],
    returns     => 'HashRef',
    description => <<'' Returns the current count of friends, followers,
updates (statuses) and favorites of the authenticating user.

);

account_totals — no params, nothing required, returns a HashRef with the current count of friends, followers, updates (statuses) and favorites of the authenticating user. Just the numbers, no drama. 📊

twitter_api_method account_settings => (
    path => 'account/settings',
    method => 'GET',
    params => [],
    required => [],
    returns     => 'HashRef',
    description => <<'' Returns the current trend, geo and sleep time
information for the authenticating user.

);

account_settings — no params, nothing required, HashRef back. Gives you the current trend, geo and sleep time information for the authenticating user. Yes, sleep time. Twitter said go to bed. 😴

twitter_api_method suggestion_categories => (
    path        => 'users/suggestions',
    method      => 'GET',
    params      => [],
    required    => [],
    returns     => 'ArrayRef',
    description => <<'' Returns the list of suggested user categories.
The category slug can be used in the "user_suggestions" API method get
the users in that category .  Does not require authentication.

);

suggestion_categories — no params, nothing required, returns an ArrayRef. It hands you the list of suggested user categories, and that category slug can then be used in the user_suggestions API method to get the users in that category. Does not require authentication. Free access, we love to see it. 🎉

twitter_api_method user_suggestions => (
    aliases     => [qw/follow_suggestions/],
    path        => 'users/suggestions/:category/members',
    method      => 'GET',
    params      => [qw/category lang/],
    required    => [qw/category/],
    returns     => 'ArrayRef',
    description => <<'' Access the users in a given category of the
Twitter suggested user list and return their most recent status if they
are not a protected user. Currently supported values for optional
parameter "lang" are "en", "fr", "de", "es", "it".  Does not require
authentication.

);

user_suggestions — note the alias, follow_suggestions, so you can call it either way. 💫

It accesses the users in a given category of the Twitter suggested user list and returns their most recent status, as long as they're not a protected user. Requires category; optionally takes lang, and right now the supported values for lang are en, fr, de, es, it. Does not require authentication. 🌍

twitter_api_method show_direct_message => (
    path => 'direct_messages/show/:id',
    method      => 'GET',
    params      => [qw/id include_entities/],
    booleans => [qw/include_entities/],
    required    => [qw/id/],
    returns     => 'HashRef',
    description => <<'' Returns a single direct message, specified by an
id parameter. Like the "direct_messages" request, this method will
include the user objects of the sender and recipient.  Requires
authentication.

);

show_direct_message — returns a single DM, specified by an id parameter. Just like the direct_messages request, it'll include the user objects of the sender and the recipient. Needs id, returns HashRef, has one boolean (include_entities). Requires authentication. 🔒

twitter_api_method retweeted_to_user => (
    path => 'statuses/retweeted_to_user',
    method      => 'GET',
    params      => [qw/id user_id screen_name/],
    required    => [qw/id/],
    returns     => 'ArrayRef',
    description => <<'' Returns the 20 most recent retweets posted by
users the specified user follows. The user is specified using the
user_id or screen_name parameters. This method is identical to
"retweeted_to_me" except you can choose the user to view.  Does not
require authentication, unless the user is protected.

);

retweeted_to_user — returns the 20 most recent retweets posted by users that the specified user follows. You specify that user with the user_id or screen_name parameters. It's identical to retweeted_to_me, except you get to choose the user to view. Requires id, returns ArrayRef. Does not require authentication — unless the user is protected. 🛡️

twitter_api_method retweeted_by_user => (
    path        => 'statuses/retweeted_by_user',
    method      => 'GET',
    params      => [qw/id user_id screen_name/],
    required    => [qw/id/],
    returns     => 'ArrayRef',
    description => <<'' Returns the 20 most recent retweets posted by
the specified user. The user is specified using the user_id or
screen_name parameters. This method is identical to "retweeted_by_me"
except you can choose the user to view.  Does not require
authentication, unless the user is protected.

);

retweeted_by_user — returns the 20 most recent retweets posted by the specified user (specified via user_id or screen_name). Identical to retweeted_by_me, except you choose whose feed you're peeking at. Requires id, returns ArrayRef. Does not require authentication, unless the user is protected. 👀

twitter_api_method lookup_friendships => (
    path        => 'friendships/lookup',
    method      => 'GET',
    params      => [qw/user_id screen_name/],
    required    => [],
    returns     => 'ArrayRef',
    description => <<'' Returns the relationship of the authenticating
user to the comma separated list or ARRAY ref of up to 100 screen_names
or user_ids provided. Values for connections can be: following,
following_requested, followed_by, none.  Requires authentication.

);

lookup_friendships — returns the relationship of the authenticating user to a comma-separated list (or ARRAY ref) of up to 100 screen names or user IDs you provide. Nothing is required, returns ArrayRef. The possible values for connections are: following, following_requested, followed_by, none. And yep — requires authentication. 💜

💖 `update_friendship`

bestie this is the "you're muted… no wait, you're unmuted" button of Twitter 💅 — it flips retweets and device notifications on or off for a specific user. Every other value? assumed false, no cap. And yeah, auth is required.

twitter_api_method update_friendship => (
    path        => 'friendships/update',
    method      => 'POST',
    params      => [qw/id user_id screen_name device retweets/],
    required    => [qw/id/],
    booleans    => [qw/device retweets/],
    returns     => 'HashRef',
    description => <<'', Allows you enable or disable retweets and device
notifications from the specified user. All other values are assumed to
be false.  Requires authentication.

);

🦋 `related_results`

gives you replies + mentions related to a status, if they exist. There is no guarantee there'll be any in the response, so don't come for me if it's empty 😭. Also it's only for the #newtwitter girlies (iykyk). Auth required.

twitter_api_method related_results => (
    path        => 'related_results/show/:id',
    method      => 'GET',
    params      => [qw/id/],
    required    => [qw/id/],
    returns     => 'ArrayRef[Status]',
    description => <<'', If available, returns an array of replies and
mentions related to the specified status. There is no guarantee there
will be any replies or mentions in the response. This method is only
available to users who have access to #newtwitter.  Requires
authentication.

);

🎀 Lists 🎀

okay NOW we're in the list era and it's iconic. buckle up 🫶

🌸 `all_subscriptions`

every list the user (or the authenticating user) is subscribed to, including their own. Pass user_id or screen_name; if you pass neither, it just uses the auth'd user. simple as.

twitter_api_method all_subscriptions => (
    path        => 'lists/all',
    method      => 'GET',
    params      => [qw/user_id screen_name count cursor/],
    required    => [],
    returns     => 'ArrayRef[List]',
    aliases     => [qw/all_lists list_subscriptions/],
    description => <<'', Returns all lists the authenticating or
specified user subscribes to, including their own. The user is specified
using the user_id or screen_name parameters.  If no user is given, the
authenticating user is used.

);

⭐ `list_statuses`

the tweet timeline for the members of a list. fun history lesson: retweets used to not show up in list timelines, but now you can pass include_rts=true to get those retweet objects too 🔥

twitter_api_method list_statuses => (
    path        => 'lists/statuses',
    method      => 'GET',
    params      => [qw/
        list_id slug owner_screen_name owner_id since_id max_id per_page page
        include_entities include_rts
    /],
    required    => [],
    booleans    => [qw/include_entities include_rts/],
    returns     => 'ArrayRef[Status]',
    description => <<'', Returns tweet timeline for members of the
specified list. Historically, retweets were not available in list
timeline responses but you can now use the include_rts=true parameter to
additionally receive retweet objects.

);

💅 `delete_list_member`

yeets a member off the list. You gotta be the list's owner to do it — no borrowing other people's lists, bestie.

twitter_api_method delete_list_member => (
    path        => 'lists/members/destroy',
    method      => 'POST',
    params      => [qw/list_id slug user_id screen_name
owner_screen_name owner_id/],
    required    => [],
    returns     => 'User',
    aliases     => [qw/remove_list_member/],
    description => <<'', Removes the specified member from the list. The
authenticated user must be the list's owner to remove members from the
list.

);

🌈 `list_memberships`

which lists has this user been added to? Pass no user_id/screen_name and you get the auth'd user's memberships instead. cute.

twitter_api_method list_memberships => (
    path        => 'lists/memberships',
    method      => 'GET',
    params      => [qw/user_id screen_name cursor
filter_to_owned_lists/],
    required    => [],
    booleans    => [qw/filter_to_owned_lists/],
    returns     => 'Hashref',
    description => <<'', Returns the lists the specified user has been
added to. If user_id or screen_name are not provided the memberships for
the authenticating user are returned.

);

🎀 `list_subscribers`

who's subscribed to the list? Private list subscribers only show up if you own that list — so it's giving locked-door energy 🔒

twitter_api_method list_subscribers => (
    path        => 'lists/subscribers',
    method      => 'GET',
    params      => [qw/list_id slug owner_screen_name owner_id cursor
include_entities skip_status/],
    required    => [],
    booleans    => [qw/include_entities skip_status/],
    returns     => 'Hashref',
    description => <<'', Returns the subscribers of the specified list.
Private list subscribers will only be shown if the authenticated user
owns the specified list.

);

✨ `subscribe_list`

the auth'd user subscribes to the list. that's it. that's the method. go off 💖

twitter_api_method subscribe_list => (
    path        => 'lists/subscribers/create',
    method      => 'POST',
    params      => [qw/owner_screen_name owner_id list_id slug/],
    required    => [],
    returns     => 'List',
    description => <<'', Subscribes the authenticated user to the
specified list.

);

🦋 `is_list_subscriber`

vibe check: is this user subscribed to this list? Returns the user, or undef if not — so maybe is doing a lot of heavy lifting here. alias is_subscribed_list too.

twitter_api_method is_list_subscriber => (
    path        => 'lists/subscribers/show',
    method      => 'GET',
    params      => [qw/
        owner_screen_name owner_id list_id slug user_id screen_name
        include_entities skip_status
    /],
    required    => [],
    booleans    => [qw/include_entities skip_status/],
    returns     => 'Maybe[User]',
    aliases     => [qw/is_subscribed_list/],
    description => <<'', Check if the specified user is a subscriber of
the specified list. Returns the user or undef.

);

and then it wraps both aliases so you get the undef handling for free, no cap:

around [qw/is_list_subscriber is_subscribed_list/] => sub {
    my $orig = shift;
    my $self = shift;

    $self->_user_or_undef($orig, 'subscriber', @_);
};

🌸 `unsubscribe_list`

the opposite of subscribe, obvi. auth'd user dips out of the list.

twitter_api_method unsubscribe_list => (
    path        => 'lists/subscribers/destroy',
    method      => 'POST',
    params      => [qw/list_id slug owner_screen_name owner_id/],
    required    => [],
    returns     => 'List',
    description => <<'', Unsubscribes the authenticated user from the
specified list.

);

🔥 `members_create_all`

bulk-add besties 💅 you can pass an arrayref or a comma-separated string of ids/screen names. But real talk: you must own the list, lists cap at 500 members, and you can only add up to 100 at a time. pace yourself.

twitter_api_method members_create_all => (
    path        => 'lists/members/create_all',
    method      => 'POST',
    params      => [qw/list_id slug owner_screen_name owner_id/],
    required    => [],
    returns     => 'List',
    aliases     => [qw/add_list_members/],
    description => <<'', Adds multiple members to a list, by specifying
a reference to an array or a comma-separated list of member ids or
screen names. The authenticated user must own the list to be able to add
members to it. Note that lists can't have more than 500 members, and you
are limited to adding up to 100 members to a list at a time with this
method.

);

💀 `members_destroy_all`

bulk-remove. arrayref of member ids/screen names, or a comma-separated string of them. Same rules as the add version: must own the list, 500 members max, 100 removed at a time max.

⚠️ real one: rapidly removing + re-adding memberships on the same list can cause issues. Take care that you're not flip-flopping too fast on one list, fr fr.

twitter_api_method members_destroy_all => (
    path        => 'lists/members/destroy_all',
    method      => 'POST',
    params      => [qw/list_id slug user_id screen_name
owner_screen_name owner_id/],
    required    => [],
    returns     => 'List',
    aliases     => [qw/remove_list_members/],
    description => <<'EOT', Removes multiple members from a list, by
specifying a reference to an array of member ids or screen names, or a
string of comma separated user ids or screen names.  The authenticated
user must own the list to be able to remove members from it. Note that
lists can't have more than 500 members, and you are limited to removing
up to 100 members to a list at a time with this method.

Please note that there can be issues with lists that rapidly remove and
add memberships. Take care when using these methods such that you are
not too rapidly switching between removals and adds on the same list.

EOT );

⭐ `is_list_member`

is this user in the list? Returns the user, or undef. the Maybe[User] energy again 😌

twitter_api_method is_list_member => (
    path        => 'lists/members/show',
    method      => 'GET',
    params      => [qw/
        owner_screen_name owner_id list_id slug user_id screen_name
        include_entities skip_status
    /],
    required    => [],
    booleans    => [qw/include_entities skip_status/],
    returns     => 'Maybe[User]',
    description => <<'', Check if the specified user is a member of the
specified list. Returns the user or undef.

);

and yep, this one gets the undef-friendly wrapper too:

around is_list_member => sub {
    my $orig = shift;
    my $self = shift;

    $self->_user_or_undef($orig, 'member', @_);
};

🎀 `list_members`

everybody in the list. Private list members only show if you own the list — locked door again 🔒

twitter_api_method list_members => (
    path        => 'lists/members',
    method      => 'GET',
    params      => [qw/
        list_id slug owner_screen_name owner_id cursor
        include_entities skip_status
    /],
    required    => [],
    booleans    => [qw/include_entities skip_status/],
    returns     => 'Hashref',
    description => <<'', Returns the members of the specified list.
Private list members will only be shown if the authenticated user owns
the specified list.

);

💜 `add_list_member`

add one member. You must own the list, and reminder: lists can't have more than 500 members. that's the whole vibe.

twitter_api_method add_list_member => (
    path        => 'lists/members/create',
    method      => 'POST',
    params      => [qw/list_id slug user_id screen_name
owner_screen_name owner_id/],
    required    => [],
    returns     => 'User',
    description => <<'', Add a member to a list. The authenticated user
must own the list to be able to add members to it. Note that lists can't
have more than 500 members.

);

💅 `delete_list`

deletes the list. You must own it to destroy it, periodt.

twitter_api_method delete_list => (
    path        => 'lists/destroy',
    method      => 'POST',
    params      => [qw/owner_screen_name owner_id list_id slug/],
    required    => [],
    returns     => 'List',
    description => <<'', Deletes the specified list. The authenticated
user must own the list to be able to destroy it.

);

✨ `update_list`

edits the list. Ownership required, as always.

twitter_api_method update_list => (
    path        => 'lists/update',
    method      => 'POST',
    params      => [qw/list_id slug name mode description
owner_screen_name owner_id/],
    required    => [],
    returns     => 'List',
    description => <<'', Updates the specified list. The authenticated
user must own the list to be able to update it.

);

🌈 `create_list`

brand-new list for the auth'd user 🎉 but heads up: you can't create more than 20 lists per account. twenty. that's the cap. choose wisely bestie.

twitter_api_method create_list => (
    path        => 'lists/create',
    method      => 'POST',
    params      => [qw/list_id slug name mode description
owner_screen_name owner_id/],
    required    => [],
    returns     => 'List',
    description => <<'', Creates a new list for the authenticated user.
Note that you can't create more than 20 lists per account.

);

🦋 `get_lists`

all the lists for the specified (or authenticating) user. Private lists get included if the auth'd user is the same user whose lists you're pulling. alias list_lists if that's more your vibe.

twitter_api_method get_lists => (
    path        => 'lists',
    method      => 'GET',
    params      => [qw/user_id screen_name cursor/],
    required    => [],
    returns     => 'Hashref',
    aliases     => [qw/list_lists/],
    description => <<'', Returns the lists of the specified (or
authenticated) user. Private lists will be included if the authenticated
user is the same as the user whose lists are being returned.

);

⭐ `get_list`

one specific list. Private lists only show if you own them — you already know the drill 💅

twitter_api_method get_list => (
    path        => 'lists/show',
    method      => 'GET',
    params      => [qw/list_id slug owner_screen_name owner_id/],
    required    => [],
    returns     => 'List',
    description => <<'', Returns the specified list. Private lists will
only be shown if the authenticated user owns the specified list.

);

twitter_api_method subscriptions => (
    path        => 'lists/subscriptions',
    method      => 'GET',
    params      => [qw/user_id screen_name count cursor/],
    required    => [],
    returns     => 'ArrayRef[List]',
    aliases     => [],
    description => <<'', Obtain a collection of the lists the specified
user is subscribed to, 20 lists per page by default. Does not include
the user's own lists.

);

### Legal ###

twitter_api_method get_privacy_policy => (
    path        => 'legal/privacy',
    method      => 'GET',
    params      => [],
    required    => [],
    returns     => 'HashRef',
    description => <<'', Returns Twitter's privacy policy.

);

twitter_api_method get_tos => (
    path        => 'legal/tos',
    method      => 'GET',
    params      => [],
    required    => [],
    returns     => 'HashRef',
    description => <<'', Returns the Twitter Terms of Service. These are
not the same as the Developer Rules of the Road.

);

1;

__END__

okay so subscriptions is the one that shows you who a user is following in list-form — lists/subscriptions, a GET, takes user_id, screen_name, count, and cursor, needs nothing required from you, hands back an ArrayRef[List], and it gives you 20 lists per page by default 💅 and does NOT include the user's own lists, bestie, read that twice 🫶

then the ### Legal ### era 🎀

get_privacy_policy hits legal/privacy with a GET, no params, no required, returns a HashRef — it literally returns Twitter's privacy policy 📜
get_tos hits legal/tos with a GET, no params, no required, returns a HashRef — it returns the Twitter Terms of Service, and heads up: these are not the same as the Developer Rules of the Road 🚨 (iconic of them honestly)

and then the file goes 1; and __END__, because even a Moose role needs to end the party eventually ✨

💖 NAME 💖

Net::Twitter::Role::API::REST — a definition of the Twitter REST API as a Moose role 🦋

✨ VERSION ✨

version 4.01043 ⭐

🌸 SYNOPSIS 🌸

package My::Twitter;
use Moose;
with 'Net::Twitter::API::REST';

that's the whole vibe, bestie — with it and you're in 👑

🎀 DESCRIPTION 🎀

Net::Twitter::Role::API::REST provides definitions for all the Twitter REST API methods. and the way that it works is: applying this role to any class provides methods for all of the Twitter REST API methods. so like, slap it on your class and every method just shows up, no cap 🫶✨

👑 AUTHOR 👑

Marc Mims <marc@questright.com> 💌

🌈 LICENSE 🌈

the Twitter API itself, and the description text used in this module, is:

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself. 🐪💜

💀 DISCLAIMER OF WARRANTY 💀

okay bestie, this next bit is the lawyers talking and I am not paraphrasing it, because it's legally real and also lowkey terrifying, so here it is in full:

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENSE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

translation: it's free, there's no warranty, you're on your own, and nobody's paying for your lost data 😭💅 periodt.

and that's a wrap on the whole page, bestie!! 🎉 this was perl v5.34.0 energy, dated 2022-06-16, and the page you just finished reading is Net::T...I::REST(3pm) — go forth and slay your API calls 🦋🌸💖

📦 where this page comes from

debian bookworm: libnet-twitter-perl 4.01043-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
debian trixie: libnet-twitter-perl 4.01043-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
ubuntu noble: libnet-twitter-perl 4.01043-2 · Artistic-1.0-Perl OR GPL-1.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms

Net::T...I::REST(3pm)

✨ Net::T...I::REST (3pm) ✨

🎀 params, mid-list, we're just rolling with it

💫 twitter_api_method destroy_status

🦋 twitter_api_method friends — deprecated, bestie 😭

🌈 twitter_api_method followers — also deprecated 🥲

👑 twitter_api_method show_user

🧚 twitter_api_method contributees

🍓 twitter_api_method contributors

💌 twitter_api_method direct_messages

📤 twitter_api_method sent_direct_messages

✉️ twitter_api_method new_direct_message

💀 twitter_api_method destroy_direct_message

🔗 twitter_api_method show_friendship

🫂 twitter_api_method create_friend

💔 twitter_api_method destroy_friend

🦋 twitter_api_method friendship_exists

friendship_exists — the mutuals check 🫶

no_retweet_ids 🙈

friends_ids 💫

followers_ids 🌸

verify_credentials — the vibe check ✅

end_session 👋

update_location 💀

update_delivery_device 📱

update_profile_colors 🎨

update_profile_image 🖼️

update_profile_background_image 🌈

rate_limit_status ⏳

update_profile 👑

favorites ⭐

create_favorite 💖

destroy_favorite 💔

enable_notifications 🔔

disable_notifications 🔕

create_block 🚫

💖 update_friendship

🦋 related_results