Collections are a type of timeline that can be controlled and hand-curated, or programmed using an API.
As a unit, collections operate under the following rules:
- Collections are created by users.
- Each collection has a name and description.
- The collection creator can add any public Tweet to the collection.
- When new Tweets are added, they appear at the top of the collection.
- Collections are public, have their own URL on twitter.com, and are viewable by all.
By design, collections do not implement specific rules or logic for sourcing or adding Tweets, leaving that strategy entirely up to you. For example if you want a collection that sources Tweets from multiple lists + a search + your own secret sauce, you can build that easily using the API.
Differences with other methods¶
Those familiar with Twitter’s family of REST APIs may notice some differences in object structure compared to typical APIs.
Pay close attention to the differences in how collections are presented — often they will be decomposed, efficient objects with information about users, Tweets, and timelines grouped, simplified, and stripped of unnecessary repetition.
Navigating collections also differs from the other APIs in that the collection is not strictly creation-time oriented. Navigating by
last_id has been replaced with a position-based pagination system that should still be familiar.
See Response structures for a deeper overview of these differences.
It is important to note that the Twitter API is strict about character encoding in OAuth 1.0a and HTTP. Reserved characters in query strings and
application/x-www-form-urlencoded POST bodies must first be encoded according to RFC 3986.
OAuth 1.0a handles requests of other content-types slightly differently. A POST body that is not
application/x-www-form-urlencoded is not considered as part of the parameters that will be encoded in the OAuth signature base string. Instead your signature base string will contain only any parameters contained on the query string and the oauth_* parameters that are typically part of the OAuth signature generation process. POST collections / entries / curate uses
application/json POST bodies.
Working with the Collections API¶
Use these methods to browse Collections, whether by ID, those owned by a specific user, or those containing a specific Tweet.
These methods allow you to create, modify, or delete a collection on behalf of the currently authenticated user.
To curate a collection, add or remove Tweets with these methods:
Collections on Twitter.com¶
Once created, Collections are available to view on twitter.com through a web and mobile-friendly permalink. Collections are meant to be shared with the world! Feel free to Tweet these permalink URLs to share your collection with followers.
Each Collections permalink is indicated in the
custom_timeline_url field found in Collection
timeline object responses.
Embedded Collections on the Web¶
Accounts with protected Tweets and Collections¶
Some accounts on Twitter have enabled a setting that “protects” the Tweets they create for an approved audience of followers. Users with protected accounts can still use Collections, but with the following caveats:
- Protected accounts can create Collections but the Collections they create will be public.
- Public users can switch to a protected state, but their Collections will remain public.
- Any user can retrieve/discover Collections belonging to any other user, regardless of the Collection owner’s protected account status.
- Tweets created by users with protected accounts cannot be included in Collections.