SuperTweet.net REST API Documentation

The SuperTweet.net Twitter MyAPI Proxy implements almost the complete Twitter API, as described at Twitter API Documentation. Simply substitute the hostname api.supertweet.net instead of api.twitter.com and use your SuperTweet.net Basic Auth credentials instead of your actual twitter username/password.

For example, to send a tweet, use the /1/statuses/update.format such as:

curl -u user:password -d "status=playing with cURL and the SuperTweet.net API" http://api.supertweet.net/1/statuses/update.xml

Other examples:

• Home Timeline
  curl -u user:password http://api.supertweet.net/1/statuses/home_timeline.xml
• Show members of a List
  curl -u user:password http://api.supertweet.net/1/ACLU/aclu-affiliates/members.xml
• Send a Direct Message
  curl -u user:password -d "text=There's no place like 127.0.0.1&user=user_2" http://api.supertweet.net/1/direct_messages/new.xml
• Create a Block
  curl -u user:password -d "" http://api.supertweet.net/1/blocks/create/mrblog.xml

Implemented API Services

The following API services are available on the api.supertweet.net server.

/1/statuses/home_timeline.format
/1/statuses/user_timeline.format
/1/statuses/public_timeline .format
/1/statuses/user_timeline .format
/1/statuses/mentions.format
/1/statuses/retweeted_by_me.format
/1/statuses/retweeted_to_me.format
/1/statuses/retweets_of_me.format
/1/statuses/retweet/{id}.format
/1/statuses/show/{id}.format
/1/statuses/retweets/{id}.format
/1/statuses/{id}/retweeted_by.format
/1/statuses/{id}/retweeted_by/ids.format
/1/users/show.format
/1/users/lookup.format
/1/users/search.format
/1/users/suggestions.format
/1/users/suggestions/{slug}.format
/1/statuses/friends.format
/1/statuses/followers.format
/1/{user}/lists.format
/1/{user}/lists/{id}.format
/1/{user}/lists/memberships.format
/1/{user}/lists/subscriptions.format
/1/{user}/{list_id}/members.format
/1/{user}/{list_id}/subscribers.format
/1/{user}/{list_id}/members/{id}.format
/1/{user}/{list_id}/subscribers/{id}.format
/1/direct_messages.format
/1/direct_messages/sent.format
/1/direct_messages/new.format
/1/direct_messages/destroy/{id}.format
/1/friendships/create/{id}.format
/1/friendships/destroy/{id}.format
/1/friendships/exists.format
/1/friendships/show.format
/1/friendships/incoming.format
/1/friendships/outgoing.format
/1/friends/ids.format
/1/followers/ids.format
/1/account/rate_limit_status.format
/1/account/update_delivery_device.format
/1/account/update_profile_colors.format
/1/account/update_profile.format
/1/favorites.format
/1/favorites/create/{id}.format
/1/favorites/destroy/{id}.format
/1/notifications/follow/{id}.format
/1/notifications/leave/{id}.format
/1/blocks/create/{id}.format
/1/blocks/destroy/{id}.format
/1/blocks/exists/{id}.format
/1/blocks/blocking.format
/1/blocks/blocking/ids.format
/1/report_spam.format
/1/saved_searches.format
/1/saved_searches/show/{id}.format
/1/saved_searches/create.format
/1/saved_searches/destroy/{id}.format
/1/geo/nearby_places.format
/1/statuses/update.format
/1/statuses/destroy/{id}.format


The above api.supertweet.net API services should pass the exact same data of the corresponding direct Twitter API, including any error codes and error message, in the exact same XML or JSON format as specified by the .format part of the request.

We have left out some API requests that don't need authorization.

---

HTTP Response Codes and Errors

Upon executing a proxied Twitter API request, whether successful or not, the SuperTweet.net API returns the response status code and any error messages received from the Twitter API. This means that even if the SuperTweet.net proxy request succeeded, in the sense that the Twitter API was invoked, an error status code and corresponding error message may still be returned, as a result of an error on the Twitter side. A special header is provided in the response, set by the SuperTweet.net API proxy, as follows:

X-TwitterAPI-Status: status-code

If this header exists in the response, then the status code and error message represent those returned by the Twitter API. If this special header is not present in the response, then the status code and error message are those of the SuperTweet.net API service itself (not from the Twitter API).

HTTP Status Codes

The SuperTweet.net API returns the response status code received from the Twitter API, generally defined as.

• 200 OK - Success
• 304 Not Modified - There was no new data to return.
• 400 Bad Request - The request was invalid. An accompanying error message will explain why.
• 401 Unauthorized - SuperTweet.net credentials were missing, incorrect, or invalid. Check your Access Credentials.
• 403 Forbidden - The request is understood, but it has been refused. An accompanying error message will explain why.
• 405 Method Not Allowed - The method specified in the request is not allowed for the resource identified by the request URI.
• 410 Gone - The URI requested is invalid or the resource requested does not exist.
• 500 Internal Server Error - Something is broken. In these cases, if the X-TwitterAPI-Status header is not present, please post to the SuperTweet.net group so the SuperTweet.net team can investigate. If the X-TwitterAPI-Status header is present, then this error indicates a problem with the Twitter service and in that case, Twitter suggests that one should post to the Twitter API group so the Twitter team can investigate.
• 502 Bad Gateway - Twitter is down or being upgraded.
• 503 Service Unavailable - The Twitter servers are up, but overloaded with requests. Try again later.

Error Messages

The SuperTweet.net API returns error messages as appropriate, either proxied as is from the Twitter API (when the X-TwitterAPI-Status header is present) or generated directly by the SuperTweet.net API proxy service. When the Twitter API returns error messages, it generally does so in your requested format. Occasionally it will return an HTML formatted error message body for a JSON or XML request (usually in the case of 5xx errors).