Socialwg/Social API/Twitter API

From W3C Wiki

This is an analysis of the Twitter REST API to determine some of the key functionality in the API.

The main Twitter REST API documentation is at Each of the endpoints listed below has a page with more details there.


Twitter users can create one-way relationships ("follow") to other accounts. They can post short messages called "tweets", which are delivered to the home timeline of all their followers.

The Twitter REST API uses OAuth 1.0a for authentication. Older versions of the API supported HTTP Basic authentication.

This API has 101 endpoints listed below.

Twitter clients may only call REST API endpoints so many times per 15-minute interval for a single user. See for more information.


Entities in the Twitter API are encoded with JSON. Older versions supported RSS, Atom, and XML representations.

The main entities in the Twitter API are:

An account holder -- a person or a brand. See
A single status update, with up to 140 characters of text, possibly with attached media. See
direct message ("DM")
A single one-to-one message.
Use for geolocation of tweets. See

Entities in the Twitter API are grouped into collections which are sorted in reverse chronological order. Special parameters are used to scroll through the collections.

Some endpoints only return the IDs of entities, which clients can retrieve from cache or resolve via batch lookup endpoints.

API endpoints

These are the API endpoints clustered by functionality.


POST statuses/update
POST statuses/update_with_media
GET statuses/show/<id>
POST statuses/destroy/<id>
Create (with or without media), read, and delete a single "tweet", respectively. Tweets are immutable and can't be updated.
GET statuses/oembed
Get a single status in OEmbed format.
GET statuses/lookup
Get a batch of statuses by ID in a single API request.


GET statuses/retweets/<id>
POST statuses/retweet/<id>
Get the "retweets" (shares, reposts) of a tweet, and retweet a tweet directly.
GET statuses/retweeters/ids
Get the IDs of the users who have retweeted this tweet.


GET statuses/user_timeline
Collection of all tweets created by the user.
GET statuses/retweets_of_me
Collection of tweets that have been retweeted by others.


GET statuses/home_timeline
Collection of tweets by people the user follows.
GET statuses/mentions_timeline
Collection of tweets that "mention" the user (with @nickname syntax).

Direct messages

POST direct_messages/new
GET direct_messages/show
POST direct_messages/destroy
Create, read, and delete a direct message. Direct messages are immutable.
GET direct_messages
GET direct_messages/sent
Inbox and outbox of direct messages

Social graph

POST friendships/create
GET friendships/show
POST friendships/update
POST friendships/destroy
CRUD for following other users.
GET friends/list
GET friends/ids
Get the accounts a user is following, either full user objects or just IDs
GET followers/list
GET followers/ids
Get the accounts that follow a user, either full user objects or just IDs
GET friendships/incoming
GET friendships/outgoing
For private accounts, which require user confirmation for following, these are incoming and outgoing queue of friendship requests.
GET friendships/lookup
Get a batch of friendships by ID.

Account management

GET account/verify_credentials
NOOP API endpoint to verify that OAuth credentials are correct.
GET account/settings
POST account/settings
POST account/update_delivery_device
Settings for the user.
POST account/update_profile
POST account/update_profile_background_image
POST account/update_profile_colors
POST account/update_profile_image
POST account/remove_profile_banner
POST account/update_profile_banner
GET users/profile_banner
Profile information visible to other users, including minor design elements of profile page.
GET users/contributees
GET users/contributors
Some accounts can be posted to by multiple authenticated users. These endpoints show which are available.

Blocking and muting

POST blocks/create
GET blocks/list
GET blocks/ids
POST blocks/destroy
Create, read and delete of "blocks". Blocked users cannot interact with the user directly (follow, mention, direct message).
POST mutes/users/create
GET mutes/users/ids
GET mutes/users/list
POST mutes/users/destroy
Create, read and delete of "mutes". Muted users' tweets aren't delivered to the user's home timeline, even if there is a follow relationship.
GET friendships/no_retweets/ids
Get IDs of users the user does not want to receive retweets from.

Content search

GET search/tweets
Search tweets globally by content.
POST saved_searches/create
GET saved_searches/list
GET saved_searches/show/<id>
POST saved_searches/destroy/<id>
Create, read, and delete "saved searches".


GET users/lookup
Given a batch of IDs, return full user objects.
GET users/show
Return full user object for specified user.
GET users/search
Search for users by nickname, full name, location, or other profile data.

Social graph suggestions

GET users/suggestions/<slug>
GET users/suggestions
GET users/suggestions/<slug>/members
Get suggested users to follow. Twitter's algorithm does the suggesting.


POST favorites/create
GET favorites/list
POST favorites/destroy
Create, read and destroy "favorites".

Contact lists

POST lists/create
GET lists/list
GET lists/show
POST lists/update
POST lists/destroy
Create, read, update and delete contact lists.
POST lists/members/destroy
GET lists/memberships
POST lists/members/create_all
GET lists/members/show
GET lists/members
POST lists/members/create
POST lists/members/destroy_all
Manage the members of a list.
GET lists/subscribers
POST lists/subscribers/create
GET lists/subscribers/show
POST lists/subscribers/destroy
GET lists/subscriptions
Manage the subscribers of a list. Other users can subscribe to a different user's list.
GET lists/ownerships
GET lists/statuses


POST geo/place
GET geo/id/<place_id>
Create and read places.
GET geo/similar_places
GET geo/reverse_geocode
GET geo/search
Search for places.


GET trends/place
GET trends/available
GET trends/closest


GET application/rate_limit_status
GET help/configuration
GET help/languages
GET help/privacy
GET help/tos
Service-wide information.


POST users/report_spam
Users can report other tweets as spam.


Special symbols

Content of tweets is parsed by the server, and some special symbols are handled in a particular way. It's not possible to opt out of this special handling.

URLs are shortened using the URL shortener. Spam, viruses and other hazardous sites can be filtered out by the shortener.
Tweets that match "@<nickname>" will have the <nickname> part turned into a link to<nickname>. The user with that nickname will get the tweet in their "mentions" timeline. Mentions at the beginning of a tweet like "@<nickname> foo bar baz" will not be delivered to the authors' followers if they do not also follow the user with <nickname>.
Tweets that match "#<hashtag>" will have the <hashtag> part replaced by a link to<hashtag>.


For Twitter, advertisements are "promoted tweets" that appear in a user's home timeline even if they're not following the author. The "scopes" property of a Tweet indicates to whom it is addressed (and, thus, if it's distributed because it's promoted).

See What are promoted tweets? for more information.

Twitter cards

If an URL in a tweet has an HTML representation, and that representation has Twitter-specific <meta> tags in the <head>, Twitter will render the tweet as a Twitter card. Twitter cards can show images, video, audio, or provide download links for mobile apps.


Twitter also has a streaming API. Clients do an HTTP-based long poll of a stream to get real-time updates.

Example JSON

Below is a (truncated) example JSON representation of a tweet object.

  "created_at": "Mon Aug 24 15:04:38 +0000 2015",
  "id": 635830076333027300,
  "id_str": "635830076333027328",
  "text": "This is kind of amazing, we have Homebrew Website Club meetups in 6 cities this week!",
  "source": "<a href=\"\" rel=\"nofollow\"></a>",
  "truncated": false,
  "in_reply_to_status_id": null,
  "in_reply_to_status_id_str": null,
  "in_reply_to_user_id": null,
  "in_reply_to_user_id_str": null,
  "in_reply_to_screen_name": null,
  "user":  {
    "id": 14447132,
    "id_str": "14447132",
    "name": "Aaron Parecki",
    "screen_name": "aaronpk",
    "location": "Portland, OR",
    "description": "CTO @EsriPDX R&D Center • Cofounder of #indieweb/@indiewebcamp • Maintains • Creator of",
    "url": "",
    "entities":  {...},
    "created_at": "Sat Apr 19 22:38:15 +0000 2008",
    "utc_offset": -25200,
    "time_zone": "Pacific Time (US & Canada)",
    "profile_image_url": "",
  "geo": null,
  "coordinates": null,
  "place":  {...},
  "retweet_count": 1,
  "favorite_count": 2,
  "entities":  {...},

See Also