Today, we are launching new Lists endpoints to the Twitter API v2.
The Lists endpoints launching today will allow you to build with Twitter Lists, so you can create new ways of customizing, organizing, and curating the Tweets people see in their timeline. You can create and manage Lists of accounts based on interests, topics, or follow Lists created by others. Additionally, with the v2 endpoints, you can now pin and unpin your favorite Lists to the top of your home timeline to create a more curated experience.
Given the breadth of functionality offered by these endpoints, we’ve grouped them as follows:
Manage Lists
The manage Lists endpoints allow you to customize and organize how you see Tweets in your timeline. For these endpoints, there are three methods available: POST, DELETE and PUT. The POST method allows you to create a List, the DELETE method allows you to delete a List, and the PUT method allows you to update the metadata of a List.
Note: The URI in the location header from the POST request will lead to a 404 page at this time until the lookup endpoints are released.
These endpoints have a rate limit of 300 requests per 15 minutes per user.
Manage List members
The manage List members endpoints allow you to add and remove members to a List on behalf of an authenticated user. You can use these endpoints to organize accounts based on topic, interest, or to prioritize which Tweets show up in your timeline. For these endpoints, there are two methods available: POST and DELETE. The POST method allows you to add a member to a List, and the DELETE method allows you to remove a member from a List.
Note: There are no v2 replacement endpoints for bulk adding and removing members with this release. We’re exploring building this feature on v2 in the future.
These endpoints have a rate limit of 300 requests per 15 minutes per user.
Manage List follows
The manage List follows endpoints allow you to follow and unfollow Lists that other people have already created. For these endpoints, there are two methods available: POST and DELETE. The POST method allows you to follow a List, and the DELETE method allows you to unfollow a List.
These endpoints have a rate limit of 50 requests per 15 minutes per user.
Manage pinned Lists
Manage pinned Lists is new functionality for Twitter API v2. The managed pinned List endpoints allow you to pin and unpin a List to the top of your home timeline to create a more curated experience. For these endpoints, there are two methods available: POST and DELETE. The POST method allows you to pin a List, and the DELETE method allows you to unpin a List.
These endpoints have a rate limit of 50 requests per 15 minutes per user.
Since you are making requests on behalf of authenticated users with these Lists endpoints, you must authenticate to this endpoint with OAuth 1.0a User Context and use the Access Tokens associated with a user that has authorized your App, which can be generated using the 3-legged OAuth flow.
Getting started
This endpoint is available to all developers building with the Twitter API v2. Be sure to check out our documentation for more information on how to get started.
We’re continuing to add new features and functionality to Twitter API v2. In the future, we plan to launch the Lists endpoints that allow you to retrieve Lists and their related information. Be sure to keep an eye on our public roadmap for the latest. As always, we’d love to hear what you think. Please reach out with any questions or feedback on what you’d like to see in the future.