Sign in or Join FriendFeed
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.

Table of Contents

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,

  1. 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.

  2. 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:

Sign in with FriendFeed

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.