3 ### HTTP Basic authentication
5 The API uses [HTTP Basic Authentication](https://en.wikipedia.org/wiki/Basic_access_authentication).
6 Note that this means that users with only an OpenID login cannot use the API; they have to add a
7 password to their account using the control panel on the site.
9 ### OAuth authentication
11 OAuth 1.0a authentication for API resources is also supported. Generally, StatusNet's
12 UI and API are similar to Twitter's for OAuth applications (if you're new to OAuth
13 check out [Beginner’s Guide to OAuth](http://hueniverse.com/oauth/)).
15 To use OAuth, you'll need to register your client application via the web interface
16 and obtain a consumer key and secret. You can find the interface for application
17 registration at [http://%%site.server%%/%%site.path%%settings/oauthapps](http://%%site.server%%/%%site.path%%settings/oauthapps).
21 For API methods that return [JSON](https://en.wikipedia.org/wiki/JSON), an optional
22 JSONP-style callback parameter is supported. If supplied, the response will be in
23 JSONP format with a callback of the given name. To make it easier for clients to
24 handle error conditions, HTTP error codes are suppressed, and the errors will be
25 returned in the response body when using JSONP.
29 There is currently no rate-limiting.
33 Some things to remember:
35 * %%site.name%% supports the
36 [OStatus federation protocol](https://en.wikipedia.org/wiki/OStatus) (as well as
37 [OpenMicroBlogging](https://en.wikipedia.org/wiki/OpenMicroBlogging) for backwards
38 compatibility), so many notices and friends' profiles may come from other servers.
39 * User nicknames are unique, but they are not globally unique. Use the ID number
41 * Private streams are not implemented yet.
42 * GNU social sites can be configured as private. In that case, all API methods
43 require authentication, including the public timeline (see the 'config' method
45 * If "Fancy URLs" are not enabled, urls from above need to include "index.php" at
46 the root. ( e.g. http://example.org/statusnet/api becomes http://www.example.org/statusnet/index.php/api )
47 * The `since_id` parameter does not work as documented by Twitter. Twitter says of
48 `since_id`: "There are limits to the number of Tweets which can be accessed
49 through the API. If the limit of Tweets has occured since the `since_id`, the
50 `since_id` will be forced to the oldest ID available." However, GNU social will
51 return the newest notices (or the newest back from max_id, if present)! Also, a
52 `since_id` <= 0 will be ignored.
56 ### statuses/public_timeline
58 Returns the 20 most recent notices, including repeats if they exist, from
61 ### statuses/home_timeline
63 Returns the 20 most recent notices, including repeats if they exist, posted by the
64 authenticating user and the users they follow. This is the same timeline seen by a
65 user when they login to their instance. This method is identical to
66 statuses/friends_timeline, except that this method always includes repeats.
68 ### statuses/friends_timeline
70 Alias of statuses/home_timeline
72 ### statuses/friends_timeline/:username
74 Alias of statuses/home_timeline for the specified username
78 Returns the 20 most recent mentions (notices containing @username) for the
81 This method will not include repeats in the XML and JSON responses unless the
82 include_rts parameter is set. The RSS and Atom responses will always include repeats
83 as notices prefixed with RT.
87 Alias of statuses/mentions
89 ### statuses/replies/:username
91 Alias of statuses/mentions for the specified username
93 ### statuses/user_timeline
95 Returns the 20 most recent notices posted by the authenticating user. It is also
96 possible to request another user's timeline by using the screen\_name or user_id
97 parameter. The other users timeline will only be visible if they are not protected,
98 or if the authenticating user's follow request was accepted by the protected user.
100 This method will not include repeats in the XML and JSON responses unless the
101 include_rts parameter is set. The RSS and Atom responses will always include
102 repeats as notices prefixed with RT, regardless of provided parameters.
104 ### statuses/retweeted\_to_me
108 ### statuses/retweeted\_by_me
112 ### statuses/retweets\_of_me
118 ### statuses/show/:id
120 Returns a single notice, specified by the id parameter. The notice's author will be
125 Post a new notice as the authenticating user.
127 Additional 'media' parameter allows binary multimedia uploads (images, etc.). Format
128 post data as multipart/form-data when using the 'media' parameter.
130 ### statuses/destroy/:id
132 Destroys the notice specified by the required ID parameter. The authenticating user
133 must be the author of the specified notice. Returns the destroyed notice if successful.
135 ### statuses/retweet/:id
137 Repeats a notice. Returns the original notice with repeat details embedded.
143 Returns the user's subscriptions (friends) as an array of profiles.
145 ### statuses/followers
147 Returns the user's subscribers (followers) as an array of profiles.
151 Returns extended information of a given user, specified by ID or screen name as per
152 the required id parameter.
154 ## Direct message resources
158 Returns the 20 most recent direct messages sent to the authenticating user. The XML
159 and JSON versions include detailed information about the sender and recipient user.
161 ### direct_messages/sent
163 Returns the 20 most recent direct messages sent by the authenticating user. The XML
164 and JSON versions include detailed information about the sender and recipient user.
166 ### direct_messages/new
168 Sends a new direct message to the specified user from the authenticating user.
169 Requires both the user and text parameters and must be a POST. Returns the sent
170 message in the requested format if successful.
172 ### direct_messages/destroy
176 ## Friendships resources
178 ### friendships/create
180 Allows the authenticating users to follow the user specified in the ID parameter.
181 Returns the befriended user in the requested format when successful. Returns a
182 string describing the failure condition when unsuccessful.
184 If you are already friends with the user a HTTP 403 may be returned, though for
185 performance reasons you may get a 200 OK message even if the friendship already
188 Note that users cannot subscribe to remote profiles using this API.
190 ### friendships/destroy
192 Allows the authenticating users to unfollow the user specified in the ID parameter.
193 Returns the unfollowed user in the requested format when successful. Returns a
194 string describing the failure condition when unsuccessful.
196 Users can unsubscribe to a remote profile using this API, but it's preferred to use
197 numeric IDs to nicknames.
199 ### friendships/exists
201 Test for the existence of friendship between two users. Will return true if user\_a
202 follows user_b, otherwise will return false. Authentication is required if either
203 user A or user B are protected. Additionally the authenticating user must be a
204 follower of the protected user.
208 Returns detailed information about the relationship between two users.
210 ## Friends and subscribers resources
214 Returns an array of numeric IDs for every user the specified user is subscribed to.
215 This method is powerful when used in conjunction with users/lookup.
219 Returns an array of numeric IDs for every user subscsribed to the specified user.
220 This method is powerful when used in conjunction with users/lookup.
224 ### account/verify_credentials
226 Returns an HTTP 200 OK response code and a representation of the requesting user if
227 authentication was successful; returns a 401 status code and an error message if
228 not. Use this method to test if supplied user credentials are valid.
230 ### account/end_session
234 ### account/update\_delivery_device
238 ### account/rate\_limit_status
240 Returns the remaining number of API requests available to the requesting user before
241 the API limit is reached.
243 We have no rate limit, so this always returns 150 hits left.
245 ### account/update\_profile\_background_image
247 Updates the authenticating user's profile background image. This method can also be
248 used to enable or disable the profile background image.
250 ### account/update\_profile_image
252 Updates the authenticating user's profile image. Note that this method expects raw
253 multipart data, not a URL to an image.
255 ## Favorite resources
259 Returns the 20 most recent favorite statuses for the authenticating or specified
260 user in the requested format.
262 ### favorites/create/:id
264 Favorites the status specified in the ID parameter as the authenticating user.
265 Returns the favorite status when successful.
267 ### favorites/destroy/:id
269 Un-favorites the status specified in the ID parameter as the authenticating user.
270 Returns the un-favorited status in the requested format when successful.
272 ## Notification resources
274 ### notifications/follow
278 ### notifications/leave
286 Blocks the specified user from following the authenticating user. In addition the
287 blocked user will not show in the authenticating users mentions or timeline (unless
288 retweeted by another user). If a follow or friend relationship exists it is
293 Un-blocks the user specified in the ID parameter for the authenticating user.
294 Returns the un-blocked user in the requested format when successful. If
295 relationships existed before the block was instated, they will not be restored.
309 Returns the string "ok" in the requested format with a 200 OK HTTP status code. This
310 method is great for sending a HEAD request to determine our servers current time.
314 It is strongly recommended you use HTTPS for all OAuth authorization steps.
316 ### oauth/request_token
318 Allows a Consumer application to obtain an OAuth Request Token to request user
319 authorization. This method fulfills Section 6.1 of the OAuth 1.0 authentication
320 flow. It is strongly recommended you use HTTPS for all OAuth authorization steps.
324 Allows a Consumer application to use an OAuth Request Token to request user
325 authorization. This method fulfills Section 6.2 of the OAuth 1.0 authentication
326 flow. Desktop applications must use this method (and cannot use GET oauth/authenticate).
328 ### oauth/access_token
330 Allows a Consumer application to exchange the OAuth Request Token for an OAuth
331 Access Token. This method fulfills Section 6.3 of the OAuth 1.0 authentication flow.
332 The OAuth access token may also be used for xAuth operations.
336 The search method supports the following optional URL parameters:
338 * **callback**: if supplied when using the JSON format, the response will use the
339 JSONP format with a callback of the given name.
340 * **rpp**: the number of notices to return per page, up to a max of 100.
341 * **page**: the page number (starting at 1) to return.
342 * **since_id:**: returns notices with ids greater than the given id.
346 * The search does not support operators, such as "from:", "to:" and booleans.
347 * Notice content is HTML-encoded.
351 Returns relevant notices that match a specified query.
355 To request search results in Atom, append your URL-encoded query as a parameter to
356 the search method and specify the Atom format:
358 `%%site.server%%/%%site.path%%api/search.atom?q=<query>`
362 To request search results in JSON, append your URL-encoded query as a parameter to
363 the search method and specify the JSON format:
365 `%%site.server%%/%%site.path%%api/search.json?q=<query>`
367 ## Additional resources
369 These are extensions to the Twitter API that expose additional functionality.
373 #### statusnet/groups/timeline
375 Shows a group's timeline. Similar to other timeline resources.
377 #### statusnet/groups/show
379 Show a groups profile.
381 #### statusnet/groups/create
385 #### statusnet/groups/join
389 #### statusnet/groups/leave
393 #### statusnet/groups/list
395 Show the groups a given user is a member of.
397 #### statusnet/groups/list_all
399 List all local groups.
401 #### statusnet/groups/membership
403 List the members of a given group.
405 #### statusnet/groups/is_member
407 Determine whether a given user is a member of a given group.
411 #### statusnet/tags/timeline
413 Shows a tag's timeline. Similar to other timeline resources.
417 #### statusnet/media/upload
419 Endpoint for uploading an image. Returns a URL that can be used in a status update.
420 Format post data as multipart/form-data.
424 #### statusnet/config
426 Show an instance's configuration information.
428 Of special note is the `<private>` element (config/site/private), which indicates
429 whether a site is private. When a site is configured as private every other API
430 method requires authentication, including the public timeline (`/api/statuses/public_timeline.format`).