Important Notice: Effective September 7, 2012 Twitter released version 1.1 of the Twitter API. The API implements the v1.1 version of the API. Twitter has deprecated the 1.0 version of the API. XML and RSS formats are no longer supported in the v1.1 API. All applications must use the current v1.1 API. REST API v1.1 Documentation

The Twitter SupertweetAPI Proxy implements the Twitter REST API v1.1, as described at Twitter API Documentation. Simply substitute the hostname instead of and use your Basic Auth credentials instead of your actual twitter username/password.

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

curl -u user:password -d "status=playing with cURL and the API"

Other examples:

  • Home Timeline
    curl -u user:password
  • Show members of a List
    curl -u user:password
  • Send a Direct Message
    curl -u user:password -d "text=There's no place like"
  • Create a Block
    curl -u user:password -d ""

API Endpoints

The API endpoints should pass the exact same data of the corresponding direct Twitter API, including any error codes and error message, in the exact same JSON format.

HTTP Response Codes and Errors

Upon executing a proxied Twitter API request, whether successful or not, the API returns the response status code and any error messages received from the Twitter API. This means that even if the 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 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 API service itself (not from the Twitter API).

HTTP Status Codes

The 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 - 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 group so the 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 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 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).

Solutions & Use CasesSecurity CenterPhilosophyBlog