FriendFeed is the easiest way to share online. Learn more »

FriendFeed API Documentation

This document describes version 2 of the FriendFeed API. Version 1 of the API is still supported.

Summary
Core Concepts
Reading data from FriendFeed
Publishing to FriendFeed
Advanced request options
Miscellaneous
- Valid file extensions
- /validate - Validate user credentials

Summary

The FriendFeed API enables developers to interact with the FriendFeed web site programmatically via simple HTTP requests.

Read methods

All read methods are HTTP GET requests. Some requests require authentication if the data is private or personalized. Responses are given in JSON by default. You can get responses in XML by adding format=xml to your requests.

Request	Description	Example
/feed/feed_id	Fetch the given feed	http://friendfeed-api.com/v2/feed/bret
/search?q=query	Fetch the given search results feed	http://friendfeed-api.com/v2/search?q=friendfeed
/picture/feed_id	The profile picture for the given feed	http://friendfeed-api.com/v2/picture/bret
/feedlist	Fetch the friend lists, groups, and other navigational links for the authenticated user	http://friendfeed-api.com/v2/feedlist
/feedinfo/feed_id	Fetch the meta-data about the given feed (e.g., list of subscribers)	http://friendfeed-api.com/v2/feedinfo/bret

See the documentation below for a complete list of read methods and full documentation.

Write methods

All write methods are HTTP POST requests, and they all require OAuth or HTTP Basic authentication.

Request	Description	Arguments
/entry	Creates, edits, or deletes an entry	`body`, `link?`, `to[]?`, `file[]`
/comment	Creates, edits, or deletes a comment	`entry`, `body`
/like	Creates or deletes a like	`entry`
/subscribe	Subscribes the authenticated user to a feed	`feed`
/unsubscribe	Unsubscribes the authenticated user from a feed	`feed`
/feedinfo	Update the profile name, description, or photo for a user or group	`feed?`, `name?`, `description?`, `picture?`

See the documentation below for a complete list of write methods and full documentation.

Core Concepts

Feeds

The most common operation in the FriendFeed API is downloading and reading feeds. This is the feed of Bret Taylor and all of the people he is subscribed to:

http://friendfeed-api.com/v2/feed/bret/friends

All feed URLs are of the form http://friendfeed-api.com/v2/feed/feed_id. These are the feed ids we support (they correspond exactly to the URLs on friendfeed.com):

home - The home feed for the authenticated user
USERNAME - The feed for the user or group USERNAME
USERNAME/friends - The entries from all of the users and groups the user USERNAME is subscribed to
USERNAME/comments - Entries the user USERNAME has commented on
USERNAME/likes - Entries the user USERNAME has liked
USERNAME/summary/N - The "Best of" for the user USERNAME in last N days
USERNAME/friendlikes - The entries that friends of USERNAME have liked
list/LIST_ID - The authenticated user's friend list LIST_ID
list/LIST_ID/summary/N - The "Best of" the authenticated user's friend list LIST_ID in last N days
filter/direct - Direct messages for the authenticated user
filter/discussions - Entries the authenticated user has commented on or liked
groups - Entries from all the groups the authenticated user is subscribed to
ENTRY_ID - Feed containing a single entry.
public - A sample of the most recent public entries posted to FriendFeed
summary/N - "Best of" for the authenticated user in last N days
me - The authenticated user's feed
notifications/desktop - Real-time updates corresponding to authenticated user's desktop notification settings

You can construct links to friendfeed.com from feed ids easily by linking to http://friendfeed.com/feed_id. For example, Bret's feed in the API has the URL http://friendfeed-api.com/v2/feed/bret, and his friendfeed.com URL is http://friendfeed.com/bret.

The feed output format is documented below.

Requests and data formats

The FriendFeed API supports two different output formats: JSON and XML. Specify the output format using the format paramter (JSON is the default):

http://friendfeed-api.com/v2/feed/public?format=json
http://friendfeed-api.com/v2/feed/public?format=xml

Dates are in RFC 3339 format in UTC. You can parse them with the strptime string "%Y-%m-%dT%H:%M:%SZ".

All methods are either HTTP GET or POST requests. Two formats are supported for POST request bodies: application/x-www-form-urlencoded and multipart/form-data. The latter format must be used when a file is uploaded as part of the request.

Response types

Feed

id - The feed id, e.g., "bret" or "bret/comments"
name - Display name of the feed, e.g., "Bret Taylor"
description? - Profile description, an HTML string
type - One of "user", "group", or "special"
private - true if the feed is private.
commands[]? - List of allowed commands for the authenticated user on this feed: "subscribe", "unsubscribe", "post", "dm", "admin"

Full feeds have all of the fields above, plus the following field:

entries[]{} - List of the entries in this feed.

Entry

id - The FriendFeed entry id, used to add comments/likes to the entry
url - URL of the entry page on the FriendFeed website.
date - The date the entry was posted.
body - The HTML body of the entry. URLs are turned into links. A best effort is made to resolve shortened URLs and use the final destination as the title of the link.
from{} - The user or group who posted this entry, a feed object
to[]{}? - List of feeds to which this entry was published, a list of feed objects
comments[]{}? - list of comments ordered by date
likes[]{}? - list of likes for this entry, ordered to present the authenticated user's friends first, and then all other other people who liked the entry
thumbnails[]{}? - List of thumbnails
- url - Image URL
- link - The URL the thumbnail should link to
- width? - Image width
- height? - Image height
- player? - the player for this media file (e.g., the YouTube.com <embed> code)
files[]{}? - List of files attached to this entry
- url - File URL
- type - File MIME type (e.g., "application/pdf")
- name - File name
- icon - URL of file type icon. Always 16x16.
- size? - File size in bytes
via{}? - If present, the application or service that created the entry.
- name - The name of the entry source, e.g., "Google Reader", "Bookmarklet"
- url - URL of the entry source
geo{}? - Present if the entry contains geographic information
- lat - The latitude
- long - The longitude
commands[]? - List of allowed commands for the authenticated user: "comment", "like", "unlike", "edit", "delete", "hide", "unhide"

Comment

id - The id of the comment
date - The date the comment was posted.
body - The HTML body of the comment. URLs are turned into links.
from{} - The user or group who posted this comment, a feed object
via{}? - present if comment was created by a third party application.
- name - the name of the application, e.g., "BuddyFeed"
- url - URL of the source, e.g., "http://www.codewalrus.com/buddyfeed/"
commands[]? - List of allowed commands for the authenticated user: "edit", "delete"

Like

date
from{} - The user who liked the parent entry.

Authentication

Authentication is required if the request modifies data on FriendFeed or if the request is for private data. FriendFeed supports three methods of authentication: OAuth, Installed Application Authentication and HTTP Basic Auth with a special password called a remote key. We recommend all applications use OAuth or Installed Application Authentication, as the experience is much simpler and more secure for users.

OAuth

FriendFeed supports the OAuth Core 1.0 standard. We require that your application be officially registered with FriendFeed. To get started with OAuth,

Register your application with FriendFeed to get a Consumer Key and Consumer Secret. At the time of registration, you will also specify a Callback URL (the URL we redirect users to after authorization). We do not support the oauth_callback parameter for security reasons.
Find a good OAuth library or check out our Google App Engine example app to integrate OAuth into your client. (You can also see the Google App Engine example in action at http://friendfeed-api.appspot.com/).

When you use OAuth in your application, you will also get good stats on the users using your application in your OAuth dashboard, and users will easily be able to revoke access to applications they no longer use. If you have any questions or problems with our OAuth implementation, you can get support in the FriendFeed API group.

All entries and comments created with OAuth will be credited as "from Your Application Name" with a link back to your web site.

You can use our "Sign in with FriendFeed" button to prompt users:

Installed Application Authentication

Installed Application Authentication is a modified form of OAuth where the consumer fetches access tokens using a username and password instead of a request token. This authentication mechanism is designed to be used in applications installed on the user's computer or device. Web applications and services must use OAuth or HTTP Basic Auth with Remote Keys.

You must register your application with FriendFeed to get a Consumer Key and Consumer Secret.

To request a token, the consumer makes an HTTP request to https://friendfeed.com/account/oauth/ia_access_token with the following parameters:

oauth_consumer_key: The Consumer Key.
oauth_signature_method: The signature method the Consumer used to sign the request.
oauth_signature: The signature as defined in OAuth Signing Requests.
oauth_timestamp: As defined in OAuth Nonce and Timestamp.
oauth_nonce: As defined in OAuth Nonce and Timestamp.
oauth_version:OPTIONAL. If present, value MUST be 1.0 .
ff_username: the user's username
ff_password: the user's password

The response is identical to the OAuth Access Token response.

The application can store the access token for later use. The application must not store the user's password or share the user's password with other applications or services. Installed application access tokens are automatically revoked when the user changes his or her password.

HTTP Basic Auth / Remote Keys

All FriendFeed users have a Remote Key to provide third party applications access to their FriendFeed. A FriendFeed Remote Key is just like a password, except that it is only used for third party applications, so it only provides access to the functionality defined by the API. Users can easily reset it if a third party application abuses the API.

You can authenticate with Remote Keys using HTTP Basic Authentication. The username should be the user's username, and the password should be the user's Remote Key. You can direct users to http://friendfeed.com/remotekey to get their remote key if they have not memorized it. See the FriendFeed API Application Guidelines for a complete set of recommendations of how to present authentication in your application.

All entries and comments created with Basic Auth will be credited as "from Your Application Name" with a link back to your web site if you also send the argument appid the value of your application's consumer key with your request.

Errors

FriendFeed returns appropriate HTTP status codes for API requests. In addition to the HTTP status code, FriendFeed includes error information in the response body. Error responses have a single property, errorCode, a program-readable string describing the error, e.g.:

{"errorCode":"body-required"}

Some of the most common error codes include:

feed-not-found - Unrecognized feed id/username
ARG-required - The HTTP argument ARG is required for this request, e.g., "body-required"
limit-exceeded - Request limit exceeded
forbidden - User does not have access to entry, group or other entity specified in the request
unauthorized - The request requires authentication

Reading data from FriendFeed

/feed - Read a feed

Fetch the entries from the feed with the given feed id:

http://friendfeed-api.com/v2/feed/feed id

Example: http://friendfeed-api.com/v2/feed/bret

The response is a feed. Authentication is required for private or personalized feeds.

All feeds support the following optional arguments:

start=index - Return entries starting with the given index, e.g., start=30
num=number - Return the specified number of entries starting from start, e.g., num=10
maxcomments=limit - If limit is 0, then do not include any comments. If limit is auto, then return the same number of comments as displayed by default on friendfeed.com. See Collapsing comments and likes
maxlikes=limit - If limit is 0, then do not include any likes. If limit is auto, then return the same number of likes as displayed by default on friendfeed.com. See Collapsing comments and likes
hidden=1 - If specified, include hidden entries in the response. By default, hidden entries are excluded from the response. Hidden entries include the additional property hidden indicating the entry should be hidden based on the user's preferences.
fof=1 - Include "friend-of-friend" entries in the response. By default, friend-of-friend entries are excluded from the response. See Friend-of-friend entries
raw=1 - Include raw text entry and comment bodies in addition to the HTML bodies included by default. The raw text bodies are available as rawBody on all returned entries and comments. This also adds rawLink on all entries.

/search - Search

Executes a search over the entries in FriendFeed. The default scope is over all public entries.

http://friendfeed-api.com/v2/search?q=query

Example: http://friendfeed-api.com/v2/search?q=friendfeed

The response is a feed. The query syntax is the same syntax as http://friendfeed.com/search/advanced.

For convenience, you can use "me" in place of any username, and we will replace it with the authenticated user's username, e.g., http://friendfeed-api.com/v2/search?q=friends:me+friendfeed.

/picture - Profile pictures

Get the profile picture for the specified feed:

http://friendfeed-api.com/v2/picture/feed id

Example: http://friendfeed-api.com/v2/picture/bret?size=medium

Profile pictures for feeds are available in three sizes: "small" (25x25), "medium" (50x50), and "large" (75x75). Specify the size of the picture using the size parameter.

/feedlist - Navigation list

Return the feeds displayed on the right hand side of the FriendFeed website for the authenticated user.

http://friendfeed-api.com/v2/feedlist

The response format is:

main[]{} - The main feeds at the top of everyone's sidebar, e.g., Home, My discussions, and Direct messages
lists[]{} - The authenticated user's friend lists
groups[]{} - The groups that show up by default in the Groups sidebar on friendfeed.com
searches[]{} - The authenticated user's saved searches
sections[]{} - A list representing the authenticated user's sidebar on FriendFeed. Useful for recreating the FriendFeed sidebar in your client.
- name - The display name of the section, e.g., "Friends" or "Groups" (read more about localization
- id - "friends", "groups", or "saved-searches"
- feeds - List of feeds in the section

To exactly reproduce the FriendFeed sidebar in your application, iterate over the sections in the response, rendering each as a separate navigation section.

/feedinfo - Feed information

Return information about the feed with the specified feed id:

http://friendfeed-api.com/v2/feedinfo/feed id

The response is a feed, plus the following fields:

subscriptions[]? - The users and groups this feed is subscribed to
subscribers[]? - The users subscribed to this feed
admins[]{}? - For groups, the list of group administrators
feeds[]? - For special feeds, the feeds that are contained within this feed. For example, for a friend list feed, this property lists all of the users/groups in the friend list.
services[]{}? - Services associated with the feed (e.g., Twitter or an imported blog)
- id - the service's id, e.g., "picasa"
- name - the service's official name, e.g., "Picasa Web Albums"
- url - the official URL of the service, e.g., "http://picasaweb.google.com/"
- icon - the URL of the favicon for this service
- profile? - the profile URL for this service, if any
- username? - the username for this service, if any

/entry - Read an entry

Fetch an entry with the entry id:

http://friendfeed-api.com/v2/entry/entry id

Example: http://friendfeed-api.com/v2/entry/e/3e2085104...

The response is an entry. The rawBody property, the raw text value of this entry, is always included in the response.

Fetch multiple entries with the comma separated id parameter:

http://friendfeed-api.com/v2/entry?id=entry id,entry id

Example: http://friendfeed-api.com/v2/entry?id=e/3e2085104...

The response is a feed.

/comment - Read a comment

Fetch a comment with the given comment id:

http://friendfeed-api.com/v2/comment/comment id

Example: http://friendfeed-api.com/v2/comment/e/3e2085104...

The response is a comment. The rawBody property, the raw text value of this comment, is always included in the response.

/url - Fetch entries about a URL or host

Fetching entries that link to a URL

Fetch entries that link to URL or URLs with the url parameter:

http://friendfeed-api.com/v2/url?url=URL0,URL1,...

Example: http://friendfeed-api.com/v2/url?url=http://blog.friendfeed.com/

The response is a feed. If authentication is used, private entries may be included with the response.

When authenticated, the results may be limited to only entries from the user's friends and subscribed groups by passing subscribed=1:

Example: http://friendfeed-api.com/v2/url?url=http://blog.friendfeed.com/&subscribed=1

The results may also be limited to a given set of users or groups by specifying their usernames in the from parameter:

Example: http://friendfeed-api.com/v2/url?url=http://blog.friendfeed.com/&from=bret,friendfeed-news

We attempt to resolve URL shorteners, so some entries may contain links that redirect to the specified one.

Fetching entries from a host

Fetch entries that link to URLs on a given host with the host parameter:

http://friendfeed-api.com/v2/url?host=HOST0,HOST1,...

Example: http://friendfeed-api.com/v2/url?host=blog.friendfeed.com,code.google.com

The response is a feed. If authentication is used, private entries may be included in the response.

When authenticated, the results may be limited to only entries from the user's friends and subscribed groups by passing subscribed=1:

Example: http://friendfeed-api.com/v2/url?host=code.google.com&subscribed=1

The results may also be limited to a given set of users or groups by specifying their usernames in the from parameter:

Example: http://friendfeed-api.com/v2/url?host=code.google.com&from=bret,friendfeed-news

We attempt to resolve URL shorteners, so some entries may contain links that redirect to ones in the specified host(s).

/short - Get info about an ff.im URL

Get the entry represented by the short ff.im URL:

http://friendfeed-api.com/v2/short/short code

The response is an entry. For http://ff.im/2sgJZ, "2sgJZ" is the short code.

/theme - Get a feed's theme

Get the theme for the specified feed:

http://friendfeed-api.com/v2/theme/feed id

Example: http://friendfeed-api.com/v2/theme/bret

Publishing to FriendFeed

All of the calls to publish information to FriendFeed are HTTP POST requests. You can perform test calls from a web browser using the HTTP Basic Authentication built into your browser at http://friendfeed.com/static/html/apitest.html.

Requests to FriendFeed are rate limited, which, e.g., limits the number and size of thumbnails you can upload in a day. Normal uses should fall well within our rate limits. If you encounter HTTP 403 errors because of rate limits, and you think the limit is erroneous, please let us know in the developer forum.

/entry - Create, edit, or delete an entry

Creating an entry

Publish a new entry. The request parameters are:

body=body - required - The body of the entry
link=link - The URL of the entry
comment=body - Text to be posted as a comment under the new entry
to[]=feed ids - The recipients for this post. The default value is me, the user's own feed. To post to multiple feeds, include multiple to arguments or comma-separate the list of recipients.
file[]=binary data - multipart/form-data encoded data with a filename. Attach the given image or file to this entry. We accept all common image formats and a number of common file types. If the file attachment is an image, FriendFeed will construct a thumbnail of the image and resize the large images to be smaller than 1600x1600. To attach multiple files, include multiple file arguments.
image_url[]=URL to an image - Images to attach to this entry. FriendFeed will download and build a thumbnail of the image. The thumbnail will link to the image URL. To attach multiple files, include multiple image_url arguments or comma-separate them.
audio_url[]=URL to a MP3 - MP3s to attach to this entry. To attach multiple MP3s, include multiple audio_url arguments or comma-separate them.
short=1 - Create a shortId and shortUrl for this entry at the same time. The shortUrl and shortId will be included in the response. Similar to the /short method
geo=1.0,1.0 - The geographic information for this entry. Should be in the format "float,float" (e.g., "37.392114,-122.07267").

Alternatively, you can provide all of the arguments in a single JSON argument:

json=JSON object - A JSON object containing the properties above. Comma separated parameters (to) and parameters that accept multiple values (image_url and audio_url) should be represented as JSON lists.

Examples using curl:

curl -u "username:remotekey" -d "body=Hello+World" \
     http://friendfeed-api.com/v2/entry
curl -u "username:remotekey" -d "body=Hello+World&link=http://friendfeed.com/" \
     http://friendfeed-api.com/v2/entry
curl -u "username:remotekey" -d "body=Hi+Bret&to=bret" \
     http://friendfeed-api.com/v2/entry
curl -u "username:remotekey" -d "body=Hi+Bret+and+Paul&to=bret,paul" \
     http://friendfeed-api.com/v2/entry

The response is the newly published entry.

Editing an entry

To edit an entry, you can use the same reequest parameters above, but include the id of the entry you are editing:

id=entry id - required - The id of the entry to edit.

Only fields that are present in the parameters or JSON will be edited. For example, the following request:

curl -u "username:remotekey" -d "body=Hello+World+Edited&id=e/3e208510463" \
     http://friendfeed-api.com/v2/entry

will update the body of the given entry but leave all other fields the same. To delete a property (e.g., remove an attached file), you should set the value to an empty string or empty list.

The response is the newly edited entry.

Deleting or undeleting an entry

Delete an entry by sending a POST request to /v2/entry/delete with the following parameters:

id=entry id - required - The id of the entry to delete
undelete=1 - If given, undelete the previously deleted entry

Example using curl:

curl -u "username:remotekey" -d "id=e/3e208510463" \
     http://friendfeed-api.com/v2/entry/delete

The response is the deleted entry.

/comment - Create, edit, or delete a comment

Creating a comment

Publish a new comment. The request parameters are:

entry=entry id - required - The id of the entry to comment on.
body=body - required - The text of the comment.

Or use a single parameter:

json=JSON object - A JSON object containing the properties above.

Example using curl:

curl -u "username:remotekey" -d "body=Hello+World&entry=e/ea6213b" \
     http://friendfeed-api.com/v2/comment

The response is the newly published comment.

Editing a comment

To edit a comment, you can use the same reequest parameters above, but include the id of the entry you are editing:

id=comment id - required - The id of the comment to edit.

Example using curl:

curl -u "username:remotekey" -d "body=Hello+World+Edited&id=e/ea6213b/c/fea542a" \
     http://friendfeed-api.com/v2/comment

The response is the newly edited comment.

Deleting or undeleting a comment

Delete a comment by sending a POST request to /v2/comment/delete with the following parameters:

id=comment id - required - The id of the comment to delete
undelete=1 - If given, undelete the previously deleted comment

Example using curl:

curl -u "username:remotekey" -d "id=e/ea6213b/c/fea542a" \
     http://friendfeed-api.com/v2/comment/delete

The response is the deleted comment.

/like - Create or delete a like

Creating a like

Like an entry. The request parameters are:

entry=entry id - required - The id of the entry to like.

Or use a single parameter:

json=JSON object - A JSON object containing the same property above.

Example using curl:

curl -u "username:remotekey" -d "entry=e/ea6213b" \
     http://friendfeed-api.com/v2/like

The response is the newly published like.

Deleting a like

Delete a like by sending a POST request to /v2/like/delete with the following parameters:

entry=entry id - required - The id of the entry to un-like

Example using curl:

curl -u "username:remotekey" -d "entry=e/ea6213b" \
     http://friendfeed-api.com/v2/like/delete

The response format is:

success - true

/subscribe - Subscribe to a feed

Subscribe the authenticated user to the specified feed. The request parameters are:

feed=feed id - required - the feed to which you want to subscribe
list=list id - The friend list to which you want to add the subscription. Valid values are "home" or "list/ID". If not provided, the default value is home.

The response format is:

status - "subscribed" or "requested"

This method requires that your application is officially registered, and the request must use OAuth or Basic Auth with the appid parameter containing your application's consumer key.

/unsubscribe - Unsubscribe from a feed

Subscribe the authenticated user from the specified feed. The request parameters are:

feed=feed id - required - the feed from which you want to unsubscribe
list=list id - The list from which you want to remove this subscription. Valid values are "home" or "list/ID". If not provided, the default behavior is to unsubscribe from all lists.

This method requires that your application is officially registered, and the request must use OAuth or Basic Auth with the appid parameter containing your application's consumer key.

/feedinfo - Update profile information

Update the profile information for the given user or group. The request parameters are:

feed=feed id - The ID of the user or group whose profile you are updating. If not specified, we update the profile of the authenticated user.
name=name - The full name of the user or group
description=html - The description of the user or group
picture - A new profile picture (an image file). The POST data must be encoded as multipart/form-data if the picture parameter is used.

Example using curl:

curl -u "username:remotekey" -F picture=@NewProfilePicture.jpg \
     http://friendfeed-api.com/v2/feedinfo

/hide - Hide an entry

Hide an entry from the authenticated user's feed. The request parameters are:

entry=entry id - required - The id of the entry to hide.
unhide=1 - If given, we un-hide the previously hidden entry

The response is an entry

/short - Create an ff.im URL

Obtain a shortened URL for a FriendFeed entry. The request parameters are:

entry=entry id - required - The id for the entry to shorten

The response is an entry plus the following fields:

shortId - The short id for this entry.
shortUrl - The short url for this entry (e.g. http://ff.im/shortId)

/theme - Set a feed's theme

Set the theme for the given user or group. The request parameters are:

theme=theme - The name of the theme. Valid values are default, fresh, bluewave, knot, steampunk, orion, helvetica, grasslands, bamboo, flowers, butterfly, duckhunt, and custom.
feed=feed id - optional - The ID of the user or group whose feed you are setting. If not specified, we set the theme of the authenticated user.

If setting a custom theme the following extra parameters are used:

bg=background color - The hex color representation for the background.
box=box color - The hex color representation for the background of the sidebar boxs.
bar=bar color - The hex color representation for the background of the bars on the sidebar boxes.
picture - optional - A background image. The POST data must be encoded as multipart/form-data if the picture parameter is used.
tile=1 - optional - Set to 1 if the background picture should tile.

Example using curl:

curl -u "username:remotekey" -F theme=custom -F bg=FF0000 -F box=00FF00 \
    -F bar=0000FF -F picture=@background.jpg \
    http://friendfeed-api.com/v2/theme

Advanced request options

JSON callbacks

The JSON output format supports an additional parameter callback= that wraps the JSON output in a function call to a function of your choice. This functionality is available to enable you to use the API with JavaScript within a web browser. For example, http://friendfeed-api.com/v2/feed/public?callback=foo outputs:

foo({"entries":[...]})

Using JSON and callbacks, you can place the FriendFeed API request inside a <script> tag, and operate on the results with a function elsewhere in the JavaScript code on the page.

All authentication is ignored if the callback= parameter is given, so JSON callbacks only work with public feeds.

Localization

The locale query parameter specifies the locale for localized strings in method responses. The default locale is en. We currently support 10 locales, including en, de, es, fa, fr, it, ja, ru, tr, zh-cn. We will automatically choose the closest match to the locale specified, e.g., we will choose es given es-gt.

Example: http://friendfeed-api.com/v2/feed/public?locale=de

Collapsing comments and likes

Many entries on FriendFeed have 100s or even 1000s of comments and likes. Retrieving and displaying all comments and likes for all feeds in your application can greatly reduce performance and usability. On FriendFeed, we display only a subset of the comments and likes for each entry along with links to expand the "collapsed" view to show the entire set of comments/likes. We support the maxcomments and maxlikes arguments for all feed requests to make this technique easy to support in your application as well:

maxcomments=limit - If limit is 0, then do not include any comments. If limit is auto, then return the same number of comments as displayed by default on friendfeed.com.
maxlikes=limit - If limit is 0, then do not include any likes. If limit is auto, then return the same number of likes as displayed by default on friendfeed.com.

For example, if you specify maxcomments=2 in your request, rather than getting this response:

"comments": [
  {"body":"First comment", "from":  {"id":"bret", "name":"Bret Taylor"}},
  {"body":"Second comment", "from":  {"id":"jim", "name":"Jim Norris"}},
  {"body":"Third comment", "from":  {"id":"sanjeev", "name":"Sanjeev Singh"}},
  {"body":"Fourth comment", "from":  {"id":"paul", "name":"Paul Buchheit"}},
  {"body":"Fifth comment", "from":  {"id":"ana", "name":"Ana Yang"}}
]

you would get this "collapsed" response:

"comments": [
  {"body":"First comment", "from":  {"id":"bret", "name":"Bret Taylor"}},
  {"body":"3 more comments", "placeholder": true, "num": 3}},
  {"body":"Fifth comment", "from":  {"id":"ana", "name":"Ana Yang"}}
]

If the maxcomments or maxlikes parameters are specified, then a placeholder field is included in the comments and likes lists for returned entries indicating where comments were excluded. The placeholder has the form:

placeholder - Always true, indicating the entity is the placeholder
body - The text we use for the placeholder on FriendFeed, e.g., "3 more comments" for comments or "234 other people" for likes
num - The number of comments or likes excluded. For example, if the body is "3 more comments", then num would be 3.

Example: http://friendfeed-api.com/v2/feed/bret?maxcomments=auto&maxlikes=auto

Friend-of-friend entries

On friendfeed.com, some feeds include "friend-of-friend" entries: entries that the user's friends have commented on or liked (even if the entries aren't from one of the user's own subscriptions). By default, these entries are excluded from feed responses in the API, but you can include them by including fof=1 with your feed request.

If the fof parameter is specified, then the following field is added to entries:

fof{}?
- type - comment or like
- from{} - The user who created the comment or like that caused this entry to appear, a feed object
fofHtml? - HTML describing the friend relationship used to include the entry, e.g., "<a href="/bret">Bret Taylor</a> commented on this".

Friend-of-friend entries only appear in the home feed and friend lists.

Real-time updates

You can update feeds in your application in real-time using long polling. With long polling, your application sends a cursor to FriendFeed with each request indicating the position in the update stream where the application last fetched updates. The request waits until new updates for the feed are available or a timeout expires. The response includes the value of the cursor to use in the next request. Use the empty string as the the starting value for the cursor.

Real-time update paths are similar to /feed and /search but should be prefaced with /updates.

For example: /updates/feed/bret

The real-time arguments are:

cursor=string - The realtime.cursor property from the last request or the empty string if this is the first request.
timeout=seconds - If updates are not immediately available, then wait up to this number of seconds for updates before finishing the request. If the timeout is zero, then the request finishes without waiting. The server might finish the request before the specified timeout.
updates=1 - Only include new comments and likes on returned entries. By default, all comments and likes are included for updated entries.

The feed response contains the additional property realtime with the cursor for the requested feed:

realtime{}
- cursor - Use this cursor to fetch changes to the feed. The cursor is an opaque string.

The response will include all new entries and entries that have new comments or likes. The following fields are added to entries, comments and likes:

created - if true, the entry, comment, or like was created since the time specified by the cursor query parameter.
updated - if true, the entry, comment, or like was updated since time specified by cursor query parameter. updated is set when, e.g., an entry has been edited by the user, so its body may have changed.

Address HTML

If you aren't interested in generating an entry's address HTML (e.g., "Bret Taylor to Bret's Feed, FriendFeed News") you can pass the optional parameter address_html=1 to add the following field to all entries:

addressHtml - An HTML string representing the address of the entry. This changes depending on the feed you are viewing this entry in but will always mimic the FriendFeed website.

Miscellaneous

Valid file extensions

The FriendFeed API supports uploading the following file extensions:

Images - jpg, gif, png, jpeg, bmp, tif, tiff

Audio - mp3, m3u, m4a, ogg, aac, ra, wav, wma, ac3, aif, aiff, mid, midi, swa

MS Office - doc, dot, docx, dotx, ppt, pptx, potx, ppsx, xls, xlsx, xltx, pps

Common standard formats - pdf, txt, csv, psd, ai, rtf, swf, ps, eps, vcf, kml, 3gp

Programming - py, c, cc, cxx, cpp, java, rb, cs, vb, as, pl, html, css, js

/validate - Validate user credentials

Validate the provided user authentication credentials (either OAuth or Basic Auth).

Example using curl:

curl -u "username:remotekey" http://friendfeed-api.com/v2/validate

The response is the authenticated user's feed.

FriendFeed API Documentation

Table of Contents

Summary

Read methods

Write methods

Core Concepts

Feeds

Requests and data formats

Response types

Feed

Entry

Comment

Like

Authentication

OAuth

Installed Application Authentication

HTTP Basic Auth / Remote Keys

Errors

Reading data from FriendFeed

/feed - Read a feed

/search - Search

/picture - Profile pictures

/feedlist - Navigation list

/feedinfo - Feed information

/entry - Read an entry

/comment - Read a comment

/url - Fetch entries about a URL or host

Fetching entries that link to a URL

Fetching entries from a host

/short - Get info about an ff.im URL

/theme - Get a feed's theme

Publishing to FriendFeed

/entry - Create, edit, or delete an entry

Creating an entry

Editing an entry

Deleting or undeleting an entry

/comment - Create, edit, or delete a comment

Creating a comment

Editing a comment

Deleting or undeleting a comment

/like - Create or delete a like

Creating a like

Deleting a like

/subscribe - Subscribe to a feed

/unsubscribe - Unsubscribe from a feed

/feedinfo - Update profile information

/hide - Hide an entry

/short - Create an ff.im URL

/theme - Set a feed's theme

Advanced request options

JSON callbacks

Localization

Collapsing comments and likes

Friend-of-friend entries

Real-time updates

Address HTML

Miscellaneous

Valid file extensions

/validate - Validate user credentials