REST API Documentation

Page history last edited by Alex Payne 2 weeks, 2 days ago

Introduction

Twitter exposes some of its functionality via an Application Programming Interface (API). This document is a reference for that functionality, and aims to serve as a reference for developers building tools that talk to Twitter.

 

Table of Contents

    1. Introduction
    2. Table of Contents
    3. Concepts
      1. Authentication
      2. RESTful Resources
      3. Parameters
      4. HTTP Requests
      5. HTTP Headers
      6. HTTP Status Codes
      7. Error Messages
      8. Rate Limiting
      9. Pagination Limiting
      10. Encoding
    4. Getting Started
      1. Be Nice to the Servers
      1. The Easiest Way to Play Around with the Twitter API
    5. Frequently Asked Questions
      1. How do I get “from [my_application]” appended to updates sent from my API application?
      1. How do I report bugs and request features?
      1. How should my Twitter bot follow users that follow it or inspect direct messages?
      2. How can I keep up with changes to the Twitter API?
      3. How can I reclaim an inactive Twitter account for my project or application?
    6. Status Methods
      1. public_timeline
      2. friends_timeline
      3. user_timeline
      4. show
      5. update
      6. replies
      7. destroy
    7. User Methods
      1. friends
      2. followers
      3. show
    8. Direct Message Methods
      1. direct_messages
      2. sent
      3. new
      4. destroy
    9. Friendship Methods
      1. create
      2. destroy
      3. exists
    10. Account Methods
      1. verify_credentials
      2. end_session
      3. update_location
      4. update_delivery_device
      5. update_profile_colors
      6. update_profile_image
      7. update_profile_background_image
      8. rate_limit_status
      9. update_profile
    11. Favorite Methods
      1. favorites
      2. create
      3. destroy
    12. Notification Methods
      1. follow
      2. leave
    13. Block Methods
      1. create
      2. destroy
    14. Help Methods
      1. test
      2. downtime_schedule
    15. Getting Help
    16. Authors

 

Concepts

 

Authentication

Many Twitter API methods require authentication.  All responses are relative to the context of the authenticating user.  For example, an attempt to retrieve information on a protected user who is not friends with the requesting user will fail.

 

For the time being, HTTP Basic Authentication is the only supported authentication scheme.  When authenticating via Basic Auth, use your registered username or email address as the username component. Session cookies and parameter-based login are known to work but are not officially supported.

 

The OAuth token-based authentication scheme will shortly be offered as an experimental beta release.

 

RESTful Resources

The Twitter API attempts to conform to the design principles of Representational State Transfer (REST). You’ll find that you can simply change the file extension on most any request to get results in the format of your choice. This document notes which formats are available for each method.

 

Twitter presently supports the following data formats: XML, JSON, and the RSS and Atom syndication formats.

 

Parameters

Some API methods take optional or requisite parameters. Where applicable, we’ve documented those parameters. Remember to convert to UTF-8 and URL encode parameters that take complex strings.  Please note that the page parameter begins at 1, not 0.

 

There are two special parameters in the Twitter API:

 

  • callback: Used only when requesting JSON formatted responses, this parameter wraps your response in a callback method of your choice.  For example, appending &callback=myFancyFunction to your request will result in a response body of: myFancyFunction(...).  Callbacks may only contain alphanumeric characters and underscores; any invalid characters will be stripped.
  • suppress_response_codes: If this parameter is present, all responses will be returned with a 200 OK status code - even errors.  This parameter exists to accommodate Flash and JavaScript applications running in browsers that intercept all non-200 responses.  If used, it's then the job of the client to determine error states by parsing the response body.  Use with caution, as those error messages may change.

 

HTTP Requests

Methods to retrieve data from the Twitter API require a GET request.  Methods that submit, change, or destroy data require a POST.  A DELETE request is also accepted for methods that destroy data. API Methods that require a particular HTTP method will return an error if you do not make your request with the correct method.

 

HTTP Headers

Where noted, some API methods will return different results based on HTTP headers sent by the client.  For example, most methods that allow a since parameter will also respond to an If-Modified-Since header.  Where the same behavior can be controlled by both a parameter and an HTTP header, the parameter will take precedence.

 

HTTP Status Codes

The Twitter API attempts to return appropriate HTTP status codes for every request. Here's what's going on with our various status codes:

 

  • 200 OK: everything went awesome.
  • 304 Not Modified: there was no new data to return.
  • 400 Bad Request: your request is invalid, and we'll return an error message that tells you why. This is the status code returned if you've exceeded the rate limit (see below). 
  • 401 Not Authorized: either you need to provide authentication credentials, or the credentials provided aren't valid.
  • 403 Forbidden: we understand your request, but are refusing to fulfill it.  An accompanying error message should explain why.
  • 404 Not Found: either you're requesting an invalid URI or the resource in question doesn't exist (ex: no such user). 
  • 500 Internal Server Error: we did something wrong.  Please post to the group about it and the Twitter team will investigate.
  • 502 Bad Gateway: returned if Twitter is down or being upgraded.
  • 503 Service Unavailable: the Twitter servers are up, but are overloaded with requests.  Try again later.

 

Error Messages

When the Twitter API returns error messages, it does so in your requested format.  For example, an error from an XML method might look like this:

 

<?xml version="1.0" encoding="UTF-8"?>

<hash>

  <request>/direct_messages/destroy/456.xml</request>

  <error>No direct message with that ID found.</error>

</hash>

 

Rate Limiting

Clients are allowed 100 requests per 60 sixty minute time period, starting from their first request.  The rate limited is applied to both authenticated and unauthenticated requests.  Unauthenticated requests are rate limited by IP, and authenticated requests are tracked by the requesting user ID.  POST requests (ex: updating status, sending a direct message) do not count against the rate limit, but some actions may have caps on them to prevent abuse.  

 

Notification that a client has exceeded the rate limit will be sent as JSON or XML when either is the requested format, and otherwise will be sent in plain text.  A status code of 400 will be returned when the client has exceeded the rate limit.

 

If you are developing an application that requires more frequent requests to the Twitter API, please request whitelisting and we'll get back to you, usually within 48 hours or less.

 

See also the rate_limit_status API call under Account Methods. 

 

Pagination Limiting

Clients may request up to 3,200 statuses via the page and count parameters. Requests for more than the limit will result in a reply with a status code of 200 and an empty result in the format requested.

 

Encoding

The Twitter API supports UTF-8 encoding. Please note that angle brackets ("<" and ">") are entity-encoded to prevent Cross-Site Scripting attacks for web-embedded consumers of JSON API output. The resulting encoded entities do count towards the 140 character limit.

 

When requesting XML, the response is UTF-8 encoded.  Symbols and characters outside of the standard ASCII range may be translated to HTML entities.

 

Getting Started

 

Be Nice to the Servers

In order to keep the API running smoothly, please obey the following guidelines: 

 

  • If your application does not keep local state, request only the first page of information that you need, and load additional pages only when triggered by user interaction. Use the page parameter. Avoid using the count parameter.
  • If your application keeps a local archive that persists between sessions, it's okay to request an entire timeline up to 200 statuses. Save it locally and avoid requesting it again. Then behave as above, or use the since_id parameter along with a high count to request only statuses you haven't seen before.

 

The Easiest Way to Play Around with the Twitter API

If your system has curl (and it should!), you’ve already got a great way to poke around the Twitter API. Here are some examples:

 

 

Frequently Asked Questions

 

How do I get “from [my_application]” appended to updates sent from my API application?

Just fill out this handy form!  Note that you must have a Twitter account and must be signed in.

 

How do I report bugs and request features?

You can see the list of existing issues right here.  Please check to be sure your issue hasn't already been reported.  Star an existing issue to vote for it, or add an example to an issue if it describes your bug.  Or, report a new issue if need be.

 

How should my Twitter bot follow users that follow it or inspect direct messages?

By default, Twitter sends an email the first time a user follows you or sends you a direct message.  For your bot-building pleasure, we've added the following headers to those emails:

 

  • X-TwitterEmailType - will be 'is_following' or 'direct_message'
  • X-TwitterCreatedAt - ex: Thu Aug 07 15:17:15 -0700 2008
  • X-TwitterSenderScreenName - ex: 'bob' 
  • X-TwitterSenderName - ex: 'Bob Smith' 
  • X-TwitterSenderID - ex: 12345
  • X-TwitterRecipientScreenName - ex: 'john'
  • X-TwitterRecipientName - ex: 'John Doe'
  • X-TwitterRecipientID - ex: 67890
  • X-TwitterDirectMessageID - ex: 2346346

 

How can I keep up with changes to the Twitter API?

There are a number of great ways to follow the changes we make to the Twitter API:

 

 

How can I reclaim an inactive Twitter account for my project or application?

Email username@twitter.com and our support staff will get back to you. Not all inactive usernames are available - we do give users a grace period in which they can restore their accounts after they've deleted them.

 

Status Methods

public_timeline

Returns the 20 most recent statuses from non-protected users who have set a custom user icon.  Does not require authentication.  Note that the public timeline is cached for 60 seconds so requesting it more often than that is a waste of resources.

 

URL: http://twitter.com/statuses/public_timeline.format

Formats: xml, json, rss, atom

Method(s): GET

API limit: Not applicable

 

friends_timeline

Returns the 20 most recent statuses posted by the authenticating user and that user's friends. This is the equivalent of /home on the Web. 

URL: http://twitter.com/statuses/friends_timeline.format

Formats: xml, json, rss, atom

Method(s): GET

API Limit: 1 per request 

Parameters:

  • since.  Optional.  Narrows the returned results to just those statuses created after the specified HTTP-formatted date, up to 24 hours old.  The same behavior is available by setting an If-Modified-Since header in your HTTP request.  Ex: http://twitter.com/statuses/friends_timeline.rss?since=Tue%2C+27+Mar+2007+22%3A55%3A48+GMT
  • since_id.  Optional.  Returns only statuses with an ID greater than (that is, more recent than) the specified ID.  Ex: http://twitter.com/statuses/friends_timeline.xml?since_id=12345
  • count.  Optional.  Specifies the number of statuses to retrieve. May not be greater than 200.  Ex: http://twitter.com/statuses/friends_timeline.xml?count=5 

  • page. Optional. Ex: http://twitter.com/statuses/friends_timeline.rss?page=3

 

user_timeline

Returns the 20 most recent statuses posted from the authenticating user. It's also possible to request another user's timeline via the id parameter below. This is the equivalent of the Web /archive page for your own user, or the profile page for a third party.

URL: http://twitter.com/statuses/user_timeline.format

Formats: xml, json, rss, atom

Method(s): GET

Parameters:

  • id.  Optional.  Specifies the ID or screen name of the user for whom to return the friends_timeline.  Ex: http://twitter.com/statuses/user_timeline/12345.xml or http://twitter.com/statuses/user_timeline/bob.json.
  • count.  Optional.  Specifies the number of statuses to retrieve. May not be greater than 200.  Ex: http://twitter.com/statuses/user_timeline.xml?count=5 
  • since.  Optional.  Narrows the returned results to just those statuses created after the specified HTTP-formatted date, up to 24 hours old.  The same behavior is available by setting an If-Modified-Since header in your HTTP request.  Ex: http://twitter.com/statuses/user_timeline.rss?since=Tue%2C+27+Mar+2007+22%3A55%3A48+GMT
  • since_id.  Optional.  Returns only statuses with an ID greater than (that is, more recent than) the specified ID.  Ex: http://twitter.com/statuses/user_timeline.xml?since_id=12345
  • page. Optional. Ex: http://twitter.com/statuses/user_timeline.rss?page=3

 

show

Returns a single status, specified by the id parameter below.  The status's author will be returned inline.

URL: http://twitter.com/statuses/show/id.format

Formats: xml, json

Method(s): GET

Parameters:

  • id.  Required.  The numerical ID of the status you're trying to retrieve.  Ex: http://twitter.com/statuses/show/123.xml 

 

update

Updates the authenticating user's status.  Requires the status parameter specified below.  Request must be a POST.  A status update with text identical to the authenticating user's current status will be ignored.

URL: http://twitter.com/statuses/update.format

Formats: xml, json.  Returns the posted status in requested format when successful.

Method(s): POST

Parameters:

  • status.  Required.  The text of your status update.  Be sure to URL encode as necessary.  Should not be more than 140 characters.
  • in_reply_to_status_id.  Optional.  The ID of an existing status that the status to be posted is in reply to.  This implicitly sets the in_reply_to_user_id attribute of the resulting status to the user ID of the message being replied to.  Invalid/missing status IDs will be ignored.

 

replies

Returns the 20 most recent @replies (status updates prefixed with @username) for the authenticating user.

URL: http://twitter.com/statuses/replies.format

Formats: xml, json, rss, atom

Method(s): GET

Parameters:

  • page.  Optional. Retrieves the 20 next most recent replies.  Ex: http://twitter.com/statuses/replies.xml?page=3
  • since.  Optional.  Narrows the returned results to just those replies created after the specified HTTP-formatted date, up to 24 hours old.  The same behavior is available by setting an If-Modified-Since header in your HTTP request.  Ex: http://twitter.com/statuses/replies.xml?since=Tue%2C+27+Mar+2007+22%3A55%3A48+GMT
  • since_id.  Optional.  Returns only statuses with an ID greater than (that is, more recent than) the specified ID.  Ex: http://twitter.com/statuses/replies.xml?since_id=12345

 

destroy

Destroys the status specified by the required ID parameter.  The authenticating user must be the author of the specified status.

URL: http://twitter.com/statuses/destroy/id.format

Formats: xml, json

Method(s): POST, DELETE

Parameters:

  • id.  Required.  The ID of the status to destroy.  Ex: http://twitter.com/statuses/destroy/12345.json or http://twitter.com/statuses/destroy/23456.xml

 

User Methods

friends

Returns up to 100 of the authenticating user's friends who have most recently updated, each with current status inline. It's also possible to request another user's recent friends list via the id parameter below. 

 URL: http://twitter.com/statuses/friends.format

Formats: xml, json

Method(s): GET

Parameters:

  • id.  Optional.  The ID or screen name of the user for whom to request a list of friends.  Ex: http://twitter.com/statuses/friends/12345.json or http://twitter.com/statuses/friends/bob.xml
  • page.  Optional. Retrieves the next 100 friends.  Ex: http://twitter.com/statuses/friends.xml?page=2

 

followers

Returns the authenticating user's followers, each with current status inline.  They are ordered by the order in which they joined Twitter (this is going to be changed). 

URL: http://twitter.com/statuses/followers.format

Formats: xml, json

Method(s): GET

Parameters: 

  • id.  Optional.  The ID or screen name of the user for whom to request a list of followers.  Ex: http://twitter.com/statuses/followers/12345.json or http://twitter.com/statuses/followers/bob.xml
  • page.  Optional. Retrieves the next 100 followers.  Ex: http://twitter.com/statuses/followers.xml?page=2

 

show

Returns extended information of a given user, specified by ID or screen name as per the required id parameter below.  This information includes design settings, so third party developers can theme their widgets according to a given user's preferences. You must be properly authenticated to request the page of a protected user.

URL: http://twitter.com/users/show/id.format

Formats: xml, json

Method(s): GET

Parameters:

One of the following is required:

  • id.  The ID or screen name of a user.  Ex: http://twitter.com/users/show/12345.json or http://twitter.com/users/show/bob.xml
  • email. May be used in place of "id" parameter above.  The email address of a user.  May be used in place of Ex: http://twitter.com/users/show.xml?email=test@example.com

 

Direct Message Methods

 

direct_messages

Returns a list of the 20 most recent direct messages sent to the authenticating user.  The XML and JSON versions include detailed information about the sending and recipient users.

URL: http://twitter.com/direct_messages.format

Formats: xml, json, rss, atom 

Method(s): GET

Parameters:

  • since.  Optional.  Narrows the resulting list of direct messages to just those sent after the specified HTTP-formatted date, up to 24 hours old.  The same behavior is available by setting the If-Modified-Since parameter in your HTTP request.  Ex: http://twitter.com/direct_messages.atom?since=Tue%2C+27+Mar+2007+22%3A55%3A48+GMT
  • since_id.  Optional.  Returns only direct messages with an ID greater than (that is, more recent than) the specified ID.  Ex: http://twitter.com/direct_messages.xml?since_id=12345
  • page.  Optional. Retrieves the 20 next most recent direct messages.  Ex: http://twitter.com/direct_messages.xml?page=3

 

sent

Returns a list of the 20 most recent direct messages sent by the authenticating user.  The XML and JSON versions include detailed information about the sending and recipient users. 

URL: http://twitter.com/direct_messages/sent.format

Formats: xml, json

Method(s): GET

Parameters:

  • since.  Optional.  Narrows the resulting list of direct messages to just those sent after the specified HTTP-formatted date, up to 24 hours old.  The same behavior is available by setting the If-Modified-Since parameter in your HTTP request.  Ex: http://twitter.com/direct_messages/sent.xml?since=Tue%2C+27+Mar+2007+22%3A55%3A48+GMT
  • since_id.  Optional.  Returns only sent direct messages with an ID greater than (that is, more recent than) the specified ID.  Ex: http://twitter.com/direct_messages/sent.xml?since_id=12345
  • page.  Optional. Retrieves the 20 next most recent direct messages sent.  Ex: http://twitter.com/direct_messages/sent.xml?page=3

 

new

Sends a new direct message to the specified user from the authenticating user.  Requires both the user and text parameters below.  Request must be a POST.  Returns the sent message in the requested format when successful.  

URL: http://twitter.com/direct_messages/new.format

Formats: xml, json  

Method(s): POST

Parameters:

  • user.  Required.  The ID or screen name of the recipient user.
  • text.  Required.  The text of your direct message.  Be sure to URL encode as necessary, and keep it under 140 characters.  

 

destroy

Destroys the direct message specified in the required ID parameter.  The authenticating user must be the recipient of the specified direct message.

URL: http://twitter.com/direct_messages/destroy/id.format

Formats: xml, json

Method(s): POST, DELETE

Parameters:

  • id.  Required.  The ID of the direct message to destroy.  Ex: http://twitter.com/direct_messages/destroy/12345.json or http://twitter.com/direct_messages/destroy/23456.xml

 

Friendship Methods

create

Befriends the user specified in the ID parameter as the authenticating user.  Returns the befriended user in the requested format when successful.  Returns a string describing the failure condition when unsuccessful.

URL: http://twitter.com/friendships/create/id.format

Formats: xml, json

Method(s): POST

Parameters:

  • id.  Required.  The ID or screen name of the user to befriend.  Ex: http://twitter.com/friendships/create/12345.json or http://twitter.com/friendships/create/bob.xml
  • follow.  Optional.  Enable notifications for the target user in addition to becoming friends.  Ex:  http://twitter.com/friendships/create/bob.json?follow=true

 

destroy

Discontinues friendship with the user specified in the ID parameter as the authenticating user.  Returns the un-friended user in the requested format when successful.  Returns a string describing the failure condition when unsuccessful.  

URL: http://twitter.com/friendships/destroy/id.format

Formats: xml, json

Method(s): POST, DELETE

Parameters:

  • id.  Required.  The ID or screen name of the user with whom to discontinue friendship.  Ex: http://twitter.com/friendships/destroy/12345.json or http://twitter.com/friendships/destroy/bob.xml

 

exists

Tests if a friendship exists between two users.

URL: http://twitter.com/friendships/exists.format

Formats: xml, json

Method(s): GET

Parameters:

  • user_a.  Required.  The ID or screen_name of the first user to test friendship for.
  • user_b.  Required.  The ID or screen_name of the second user to test friendship for.
  • Ex: http://twitter.com/friendships/exists.xml?user_a=alice&user_b=bob

 

Account Methods

verify_credentials

Returns an HTTP 200 OK response code and a representation of the requesting user if authentication was successful; returns a 401 status code and an error message if not.  Use this method to test if supplied user credentials are valid.

URL: http://twitter.com/account/verify_credentials.format

Formats: xml, json

Method(s): GET

 

end_session

Ends the session of the authenticating user, returning a null cookie.  Use this method to sign users out of client-facing applications like widgets.

URL: http://twitter.com/account/end_session

Formats: xml, json

Method(s): POST

 

update_location

This method has been deprecated in favor of the update_profile method below.  Its URL will continue to work, but please consider migrating to the newer and more comprehensive method of updating profile attributes.

 

update_delivery_device

Sets which device Twitter delivers updates to for the authenticating user.  Sending none as the device parameter will disable IM or SMS updates.

URL: http://twitter.com/account/update_delivery_device.format

Formats: xml, json

Method(s): POST

Parameters:

  • device.  Required.  Must be one of: sms, im, none.  Ex: http://twitter.com/account/update_delivery_device.xml?device=im

 

update_profile_colors

Sets one or more hex values that control the color scheme of the authenticating user's profile page on twitter.com.  These values are also returned in the /users/show API method.

URL: http://twitter.com/account/update_profile_colors.format

Formats: xml, json

Method(s): POST

Parameters: one or more of the following parameters must be present.  Each parameter's value must be a valid hexidecimal value, and may be either three or six characters (ex: #fff or #ffffff).

  • profile_background_color.  Optional.
  • profile_text_color.  Optional.
  • profile_link_color.  Optional.
  • profile_sidebar_fill_color.  Optional.
  • profile_sidebar_border_color.  Optional.

 

update_profile_image

Updates the authenticating user's profile image.  Expects raw multipart data, not a URL to an image.

URL: http://twitter.com/account/update_profile_image.format

Formats: xml, json

Method(s): POST

Parameters:

  • image.  Required.  Must be a valid GIF, JPG, or PNG image of less than 700 kilobytes in size.  Images with width larger than 500 pixels will be scaled down. 

 

update_profile_background_image

Updates the authenticating user's profile background image.  Expects raw multipart data, not a URL to an image.

URL: http://twitter.com/account/update_profile_background_image.format

Formats: xml, json

Method(s): POST

Parameters:

  • image.  Required.  Must be a valid GIF, JPG, or PNG image of less than 800 kilobytes in size.  Images with width larger than 2048 pixels will be scaled down.

 

rate_limit_status

Returns the remaining number of API requests available to the requesting user before the API limit is reached for the current hour. Calls to rate_limit_status do not count against the rate limit.  If authentication credentials are provided, the rate limit status for the authenticating user is returned.  Otherwise, the rate limit status for the requester's IP address is returned.

URL: http://twitter.com/account/rate_limit_status.format

Formats: xml, json

Method(s): GET

Parameters: none 

 

update_profile

Sets values that users are able to set under the "Account" tab of their settings page. Only the parameters specified will be updated; to only update the "name" attribute, for example, only include that parameter in your request.

URL: http://twitter.com/account/update_profile.format

Formats: xml, json

Method(s): POST

Parameters: one or more of the following parameters must be present.  Each parameter's value should be a string.  See the individual parameter descriptions below for further constraints.

  • name.  Optional. Maximum of 40 characters.
  • email.  Optional. Maximum of 40 characters. Must be a valid email address.
  • url.  Optional. Maximum of 100 characters. Will be prepended with "http://" if not present.
  • location.  Optional. Maximum of 30 characters. The contents are not normalized or geocoded in any way.
  • description.  Optional. Maximum of 160 characters.

 

Favorite Methods

favorites

Returns the 20 most recent favorite statuses for the authenticating user or user specified by the ID parameter in the requested format. 

URL: http://twitter.com/favorites.format

Formats: xml, json, rss, atom

Method(s): GET

Parameters:

  • id.  Optional.  The ID or screen name of the user for whom to request a list of favorite statuses.  Ex: http://twitter.com/favorites/bob.json or http://twitter.com/favorites/bob.rss
  • page.  Optional. Retrieves the 20 next most recent favorite statuses.  Ex: http://twitter.com/favorites.xml?page=3 

 

create

Favorites the status specified in the ID parameter as the authenticating user.  Returns the favorite status when successful.

URL: http://twitter.com/favorites/create/id.format

Formats: xml, json

Method(s): POST

Parameters:

  • id.  Required.  The ID of the status to favorite.  Ex: http://twitter.com/favorites/create/12345.json or http://twitter.com/favorites/create/45567.xml

 

destroy

Un-favorites the status specified in the ID parameter as the authenticating user.  Returns the un-favorited status in the requested format when successful.  

URL: http://twitter.com/favorites/destroy/id.format

Formats: xml, json

Method(s): POST, DELETE

Parameters:

  • id.  Required.  The ID of the status to un-favorite.  Ex: http://twitter.com/favorites/destroy/12345.json or http://twitter.com/favorites/destroy/23456.xml 

 

Notification Methods

follow

Enables notifications for updates from the specified user to the authenticating user.  Returns the specified user when successful.

URL:http://twitter.com/notifications/follow/id.format

Formats: xml, json

Method(s): POST

Parameters: 

  • id.  Required.  The ID or screen name of the user to follow.  Ex: http://twitter.com/notifications/follow/12345.xml or http://twitter.com/notifications/follow/bob.json

 

leave

Disables notifications for updates from the specified user to the authenticating user.  Returns the specified user when successful.

URL: http://twitter.com/notifications/leave/id.format

Formats: xml, json

Method(s): POST

Parameters: 

  • id.  Required.  The ID or screen name of the user to leave.  Ex:  http://twitter.com/notifications/leave/12345.xml or http://twitter.com/notifications/leave/bob.json

 

NOTE: The Notification Methods require the authenticated user to already be friends with the specified user otherwise the error "there was a problem following the specified user" will be returned. You create and manage friendships with these services.

 

Block Methods

create

Blocks the user specified in the ID parameter as the authenticating user.  Returns the blocked user in the requested format when successful.  You can find out more about blocking in the Twitter Support Knowledge Base.

URL: http://twitter.com/blocks/create/id.format

Formats: xml, json

Method(s): POST

Parameters:

  • id.  Required.  The ID or screen_name of the user to block.  Ex: http://twitter.com/blocks/create/12345.json or http://twitter.com/blocks/create/bob.xml

 

destroy

Un-blocks the user specified in the ID parameter as the authenticating user.  Returns the un-blocked user in the requested format when successful.  

URL: http://twitter.com/blocks/destroy/id.format

Formats: xml, json

Method(s): POST, DELETE

Parameters:

  • id.  Required.  The ID or screen_name of the user to un-block.  Ex: http://twitter.com/blocks/destroy/12345.json or http://twitter.com/blocks/destroy/bob.xml

 

Help Methods

test

Returns the string "ok" in the requested format with a 200 OK HTTP status code.

 URL: http://twitter.com/help/test.format

Formats: xml, json

Method(s): GET

 

downtime_schedule

Returns the same text displayed on http://twitter.com/home when a maintenance window is scheduled, in the requested format.  

URL:http://twitter.com/help/downtime_schedule.format

Formats: xml, json

Method(s): GET

 

Getting Help

A supplement to this document is the Twitter Development Talk Google Group. Engineers who work on Twitter follow this group closely, and many third party developers are kindly participating and lending their expertise. It’s a great place to ask questions about the Twitter API.

 

Authors

This document is maintained by Alex Payne, Twitter's API Lead.  You can reach him via email at alex@twitter.com.

 

Comments (0)

You don't have permission to comment on this page.

Printable version
 
Anonymous Create an account or Log in