The NewsBlur API
Introduction to the API

NewsBlur is a personal news reader that brings people together to talk about the world. A new sound of an old instrument.

NewsBlur's API allows users to retrieve their feeds, feed counts, feed icons, feed statistics, and individual feed stories. No API key is required, but you are required to authenticate before using any of the API endpoints. Please be considerate, and don't hammer our servers.

We're quite pleased to point out that this entire API is open-source, including the implementation of the endpoints. You can find the source of the /reader/ views source, /social/ views source, /rss_feeds/ views source, as well as the API definitions in YAML.

We love pull requests. If you want to add an endpoint, modify output, or make something better, NewsBlur's repo on Github is the place to make that happen.

A Note about OAuth

NewsBlur supports OAuth but to have an OAuth enabled client you must email Samuel to request a client ID and secret. You will need to provide your NewsBlur username, redirect URI (often just your client app's website), and app name.

To use OAuth when authenticating requests, be sure to pass the Bearer HTTP header with every request, just as you would on any other OAuth API. Use the /oauth/authorize endpoint to begin the OAuth authentication procedure. Use the /oauth/token endpoint to receive your authorized token, which you can pass in with every request.

You are not required to use OAuth, in which case you will need to pass the newsblur_sessionid cookie with every request. This cookie is set on login.

API Table of Contents
authentication
feeds
stories
social
feed management
intelligence classifiers
import/export
authentication

POST /api/login

  • Login as an existing user.
Parameter Description Default Example
username Required Username samuelclay
password Optional Password new$blur

Tips

  • If a user has no password set, you cannot just send any old password. This is not Instapaper.

POST /api/logout

  • Logout the currently logged in user.

POST /api/signup

  • Create a new user.
Parameter Description Default Example
username Required Username samuelclay
password Optional Password new$blur
email Required Email address samuel@newsblur.com
feeds

GET /rss_feeds/search_feed

  • Retrieve information about a feed from its website or RSS address.
Parameter Description Default Example
address Required Searches the RSS and website address and returns a feed. techcrunch.com
offset Optional Try paging through feeds found by using the offset. 1

GET /reader/feeds

  • Retrieve a list of feeds to which a user is actively subscribed.
  • Includes the 3 unread counts (positive, neutral, negative), as well as optional favicons.
Parameter Description Default Example
include_favicons Optional Include favicons inline. Since they can be time consuming to download, you can optionally turn them off. Use /api/v1/feeds/favicons/ to retrieve the favicons in a separate request. false true/false
flat Optional Returns a flat folder structure instead of nested folders. Useful when displaying all folders in a single depth without recursive descent. false true/false
update_counts Optional Forces recalculation of unread counts on all feeds. The preferred method is to call this endpoint without updated counts, then call refresh_feeds to get updated counts. That way you can quickly show the user's feeds, then update the counts. Turning this option on will lead to a slower load-time. false true/false

Tips

  • Use /reader/refresh_feeds to get updated unread counts.
  • Turn off include_favicons if you can either cache favicons or can wait to fetch them.

GET /reader/favicons

  • Retrieve a list of favicons for a list of feeds. Used when combined with /reader/feeds and include_favicons=false, so the feeds request contains far less data. Useful for mobile devices, but requires a second request.
Parameter Description Default Example
feed_ids Optional Array of feed ids. Leave empty to retrieve all active (enabled) feeds. feed_ids=12&feed_ids=24

Tips

  • To use inline data images, you can use this syntax:
    <img src="data:image/png;base64,[IMAGE_DATA_STRING]" />

GET /reader/page/:id

  • Retrieve the original page from a single feed.

GET /reader/refresh_feeds

  • Up-to-the-second unread counts for each active feed.
  • Poll for these counts no more than once a minute.

GET /reader/feeds_trainer

  • Retrieves all popular and known intelligence classifiers.
  • Also includes user's own classifiers.
Parameter Description Default Example
feed_id Optional Only use a single feed. Omit this to get the classifiers for all feeds at once. 42

Tips

  • If you only want a user's classifiers, use /classifiers/:id.
  • Omit the feed_id to get all classifiers for all subscriptions.

GET /rss_feeds/statistics/:id

  • Statistics and history for a feed.
  • Includes feed update frequencies, frequency distribution of intelligence classifiers, average stories per month over the life of the feed, and the last five feed and page fetches.

GET /rss_feeds/feed_autocomplete

  • Get a list of feeds that contain a search phrase.
  • Searches by feed address, feed url, and feed title, in that order.
  • Will only show sites with 2+ subscribers.
Parameter Description Default Example
term Optional Phrase to search for in feed address, url, and title. tech
stories

GET /reader/feed/:id

  • Retrieve stories from a single feed.
Parameter Description Default Example
page Optional Page of stories, starting from 1. 1 2
order Optional Story order by oldest or newest first newest oldest
read_filter Optional Show all stories or only unread stories all unread
include_hidden Optional Use this if you want to show hidden stories (provided you have a "Show Hidden Stories" button). All native NewsBlur apps (web, ios, android) use this. false true
include_story_content Optional If you're just checking for story ids and meta-data, you don't need the story content, thus reducing bandwidth. true false
query Optional Search for a keyword or phrase in the feed. Note that only premium users can search feeds. pizza

Tips

  • The story score (red, neutral, green) can be computed by following the function compute_story_score in reader_utils.js on GitHub. Alternatively, you can use the score parameter.
  • Counts are broken into three. Add them up for a total, but you shouldn't show or count the hidden stories:
    • ps: positive/focus count
    • nt: neutral/unread count
    • ng: negative/hidden count
  • If you aren't including hidden stories and a user has many stories that are hidden (which happens quite often as they might thumbs down the publisher but thumbs up a title or tag), then make sure to keep paging if the hidden_stories_count is non-zero. Don't rely on the stories list being empty to assume that's when to stop paging.

GET /rss_feeds/original_text

  • Retrieve the extracted full text for a story.
Parameter Description Default Example
story_hash Required A story hash to fetch. story_hash=123:a1d62b

GET /rss_feeds/original_story

  • Retrieve the original website for a story.
Parameter Description Default Example
story_hash Required A story hash to fetch. story_hash=123:a1d62b

GET /reader/starred_stories

  • Retrieve a user's starred stories.
Parameter Description Default Example
page Optional Page of starred stories, starting from 1. 1 2
h Optional Pass up to 100 story_hashes. Use with starred_story_hashes. h=a1b2c3&h=d4e5f6
tag Optional Only load stories under a specific saved story tag. pizza
highlights Optional Only load stories that have highlighting. true
query Optional Search for a keyword or phrase in the starred story feed. Note that only premium users can search feeds. pizza

GET /reader/starred_story_hashes

  • Retrieve the story hashes of a user's starred stories.
Parameter Description Default Example
include_timestamps Optional Including timestamps for starred_date

Tips

  • Use with /reader/starred_stories and pass up to 100 story_hashes as the h param.

GET /reader/river_stories

  • Retrieve stories from a collection of feeds. This is known as the River of News.
  • Stories are ordered in reverse chronological order.
Parameter Description Default Example
feeds Required Feed ids to use in the river. Usually every feed in a folder with unread stories. feeds=12&feeds=24
page Optional Page of stories, starting from 1. 1 2
order Optional Story order by oldest or newest first newest oldest
read_filter Optional Show all stories or only unread stories unread all
include_hidden Optional Use this if you want to show hidden stories (provided you have a "Show Hidden Stories" button). All native NewsBlur apps (web, ios, android) use this. false true
query Optional Search for a keyword or phrase in the folder. Note that only premium users can search feeds. pizza
infrequent Optional Show only stories from infrequently published sites. Specify the number of stories/month (default: 30) or specify false. false 30

Tips

  • Counts are broken into three. Add them up for a total, but you shouldn't show or count the hidden stories:
    • ps: positive/focus count
    • nt: neutral/unread count
    • ng: negative/hidden count
  • If you aren't including hidden stories and a user has many stories that are hidden (which happens quite often as they might thumbs down the publisher but thumbs up a title or tag), then make sure to keep paging if the hidden_stories_count is non-zero. Don't rely on the stories list being empty to assume that's when to stop paging.

GET /reader/river_stories

  • Retrieve up to 100 stories when specifying by story_hash.
  • Used this in conjunction with unread_story_hashes to store stories for offline use.
Parameter Description Default Example
h Required Pass up to 100 story_hashes. Use with unread_story_hashes. h=468:a1b2c3&h=7531:d4e5f6

GET /reader/unread_story_hashes

  • The story_hashes of all unread stories.
  • Useful for offline access of stories and quick unread syncing.
  • Use include_timestamps to fetch stories in date order.
Parameter Description Default Example
feed_id Optional Feed ids to check. Omit to include every feed subscription. feed_id=12&feed_id=24
include_timestamps Optional Including timestamps for story_date

GET /reader/read_stories

  • Feed of previously read stories.
Parameter Description Default Example
page Optional Page of stories, starting from 1. 1 2
order Optional Story order by oldest or newest first newest oldest

POST /reader/mark_story_hashes_as_read

  • Mark stories as read using their unique story_hash.
  • Multiple story hashes can be sent at once.
  • Mix and match stories from different feeds and social subscriptions.
Parameter Description Default Example
story_hash Required List of story hashes to mark as read. story_hash=123:a1d62b&story_hash=1456789:4e3c12

Tips

  • Throttle requests to mark as read. You don't need to send one request per story.
  • Queue up to 5 stories or once every 10 seconds before firing, whichever comes first.
  • This endpoint is newer than all of the other mark as read endpoints, so use this one. The other endpoints are maintained for old clients to use.

POST /reader/mark_story_as_read

  • Deprecated! Just send the story_hash to mark_story_hashes_as_read.
  • Mark stories as read (deprecated).
  • Multiple story ids can be sent at once.
  • Each story must be from the same feed.
Parameter Description Default Example
story_id Required List of story ids to mark as read. story_id=http://blog.newsblur.com/post/1&story_id=http://blog.newsblur.com/post/2
feed_id Required Feed id that each story is from. 42

Tips

  • Throttle requests to mark as read. You don't need to send one request per story.
  • Queue up to 5 stories or once every 10 seconds before firing, whichever comes first.

POST /reader/mark_feed_stories_as_read

  • Deprecated! Just send the story_hash to mark_story_hashes_as_read.
  • Marks multiple stories as read.
  • Multiple story ids can be sent at once.
  • Multiple feeds can be sent.
Parameter Description Default Example
feeds_stories Required JSON serialized dictionary of feed_ids to an array of story_ids. {
12: ['story_id_1', 'story_id_2'],
24: ['story_id_3']
}

Tips

  • Throttle requests to this endpoint. You don't need to send one request per story.
  • Queue up to 5 stories or once every 10 seconds before firing, whichever comes first.

POST /reader/mark_social_stories_as_read

  • Deprecated! Just send the story_hash to mark_story_hashes_as_read.
  • Marks multiple stories as read.
  • Multiple story ids can be sent at once.
  • Multiple feeds can be sent.
Parameter Description Default Example
users_feeds_stories Required JSON serialized dictionary of user_ids to feed_ids to an array of story_ids. {
user_id:
{feed_id: ['story_id_1', 'story_id_2'],
24: ['story_id_3']
}
}

Tips

  • Throttle requests to this endpoint. You don't need to send one request per story.
  • Queue up to 5 stories or once every 10 seconds before firing, whichever comes first.

POST /reader/mark_story_hash_as_unread

  • Mark a single story or multiple stories as unread using its unique story_hash.
  • Multiple story hashes can be sent at once.
  • Premium users can mark up to 30 days as unread. Free users only have 15 days.
  • If a story is too old to mark as read, look for (and display to the user) the message parameter returned back to you.
Parameter Description Default Example
story_hash Required A story hash to mark as unread. story_hash=123:a1d62b

Tips

  • This endpoint is newer than all of the other mark as read endpoints, so use this one. The other endpoints are maintained for old clients to use.

POST /reader/mark_story_hash_as_starred

  • Mark a story as starred (saved).
Parameter Description Default Example
story_hash Required Story to save, specified by hash. 64:a295ed
user_tags Optional Tags for the saved story ['cooking', 'blogs']
highlights Optional Strings to highlight ['For example', 'this sentence is highlighted.']

Tips

  • You can send a list for user_tags and highlights. user_tags[]=blog&user_tags[]=cooking

POST /reader/mark_story_hash_as_unstarred

  • Mark a story as unstarred (unsaved).
  • Multiple story hashes can be sent at once.
Parameter Description Default Example
story_hash Required Story to unsave, specified by hash. 64:a295ed

POST /reader/mark_feed_as_read

  • Mark a list of feeds as read.
Parameter Description Default Example
feed_id Required List of feed ids to mark as read. feed_id=12&feed_id=24
cutoff_timestamp Optional Timestamp for older/newer cutoff. 1400777921
direction Optional Older or newer stories should be marked as read. Use with cutoff_timestamp older

Tips

  • To mark a folder as read, send the ids of each feed inside the folder.

POST /reader/mark_all_as_read

  • Mark all stories from all feeds as read.
Parameter Description Default Example
days Optional Days back to mark as read. 0 7

Tips

  • Use 0 days back to mark everything as read.
social

GET /social/river_stories

  • Retrieve stories from a collection of social subscriptions. This is known as the River of News.
  • Stories are ordered in reverse chronological order by default.
  • Only unread stories are available.
Parameter Description Default Example
social_user_ids Required User ids to use in the river. feed_id=12&feed_id=24
page Optional Page of stories, starting from 1. 1 2
order Optional Story order by oldest or newest first newest oldest

POST /social/share_story

  • Share a story with optional comments. The story is shared on the user's blurblog.
Parameter Description Default Example
feed_id Required Feed id that the story is from. 42
story_id Required Story id to share. http://blog.newsblur.com/post/1
comments Optional The meat of the share. 42
source_user_id Optional If the story is being re-shared from another blurblog, note the user_id of the original sharer. 128
post_to_services Optional List of services to cross-post to. Can be 'twitter' and/or 'facebook'. post_to_services=twitter&post_to_service=facebook
format Optional Return JSON or a HTML template json html

POST /social/unshare_story

  • Removes a shared story from a user's blurblog. Unshares the story and removes the comments. Any replies will also be deleted. This may change.
Parameter Description Default Example
feed_id Required Feed id that the story is from. 42
story_id Required Story id to remove the existing share. http://blog.newsblur.com/post/1
format Optional Return JSON or a HTML template json html

GET /social/load_user_friends

  • This lists the user profiles of followers and followings of a user.
  • Also returns information related to which sharing services a user is using.

GET /social/profile

  • Public profile of a user. Includes common followers and common followings.
Parameter Description Default Example
user_id Required User id of user 42

GET /social/load_user_profile

  • Private details of the current user's profile and connected services.

POST /social/save_user_profile

  • Saves a user's profile details.
Parameter Description Default Example
location Optional Hometown New York City
bio Optional 160 character bio. Developer. API Designer.
website Optional Website address http://www.samuelclay.com
photo_service Optional Which photo service to use: twitter, facebook, gravatar. twitter

GET /social/interactions

  • Interactions between a user and other users.
Parameter Description Default Example
user_id Optional ID of user. Defaults to current logged in user. 42
page Optional 4 interactions per page. 2
format Optional JSON or HTML template json html

GET /social/activities

  • A user's activities: follows, shared stories, and replies to comments.
  • Also includes starred stories and new site subscriptions if fetching the currently logged in user's activities.
Parameter Description Default Example
user_id Optional ID of user. Defaults to current logged in user. 42
page Optional 4 activities per page. 2
format Optional JSON or HTML template json html

POST /social/follow

  • Follow a user and subscribe to their blurblog.
Parameter Description Default Example
user_id Required ID of user to follow. 42

POST /social/unfollow

  • Unfollow a user and unsubscribe from their blurblog.
Parameter Description Default Example
user_id Required ID of user to unfollow. 42

POST /social/mute_user

  • Mute a user to not see thier shares or replies.
Parameter Description Default Example
user_id Required ID of user to mute. 42

POST /social/unmute_user

  • Un-mute a user to see thier shares and replies.
Parameter Description Default Example
user_id Required ID of user to unmute. 42

GET /social/feed_trainer

  • Get the intelligence classifiers for a blurblog.
Parameter Description Default Example
user_id Required ID of blurblog's user. 42

GET /social/public_comments

  • Get all public comments on a shared story.
  • If you want comments from friends, they are already attached to the story from either reader/feed/:id or /social/stories/:user_id.
Parameter Description Default Example
story_id Required ID of shared story. http://blog.newsblur.com/post/1
feed_id Required ID of feed for the shared story. 42
format Optional JSON or HTML template json html

POST /social/save_comment_reply

  • Saves a reply to a comment.
  • Comments can have a number of replies, but they are all one-level deep.
  • Replying to a comment sends notifications to both original commenter and to every other replier to the comment.
Parameter Description Default Example
story_feed_id Required ID of feed the story belongs to. 42
story_id Required ID of story being commented on. http://blog.newsblur.com/post/1
comment_user_id Required ID of user who left the original comment that is now being replied to. 64
reply_comments Required The content of the reply. Brilliant analysis.
reply_id Optional If editing an existing reply, provide the original reply id so the correct reply can be overwritten. 5000...0042
format Optional Return JSON or a HTML template json html

POST /social/remove_comment_reply

  • Deletes a reply from a comment.
  • Also deletes the interactions and activities associated with the reply.
Parameter Description Default Example
story_feed_id Required ID of feed the story belongs to. 42
story_id Required ID of story being commented on. http://blog.newsblur.com/post/1
comment_user_id Required ID of user who left the original comment that is now being replied to. 64
reply_id Optional The reply's id 5000...0042
format Optional Return JSON or a HTML template json html

POST /social/like_comment

  • Favorites a comment.
  • Does not send an email to the recipient user, but they do see an interaction.
Parameter Description Default Example
story_feed_id Required ID of feed the story belongs to. 42
story_id Required ID of story being commented on. http://blog.newsblur.com/post/1
comment_user_id Required ID of user who left the original comment that is now being replied to. 64
format Optional Return JSON or a HTML template json html

POST /social/remove_like_comment

  • Un-favorites a comment.
Parameter Description Default Example
story_feed_id Required ID of feed the story belongs to. 42
story_id Required ID of story being commented on. http://blog.newsblur.com/post/1
comment_user_id Required ID of user who left the original comment that is now being replied to. 64
format Optional Return JSON or a HTML template json html

GET /social/find_friends

  • Search for a user by username, email, or blurblog title.
Parameter Description Default Example
query Required Username, email, or part of a blurblog title. samuel

GET /social/rss/:user_id/:username

  • RSS feed for a blurblog.

Tips

  • The username url parameter is optional. It's just recommended if you have it.

GET /social/stories/:user_id/:username

  • Shared stories from a user's blurblog.
  • Comments, replies, and profiles from followed users are automatically included.
Parameter Description Default Example
order Optional Story order by oldest or newest first newest oldest
read_filter Optional Show all stories or only unread stories all unread

Tips

  • The username url parameter is optional. It's just recommended if you have it.

GET /social/page/:user_id/:username

  • A user's shared stories blurblog in HTML.
  • This may also live at a custom URL, which is specified in the user's full profile.

Tips

  • The username url parameter is optional. It's just recommended if you have it.

GET /social/settings/:user_id/:username

  • A user's full profile.

Tips

  • The username url parameter is optional. It's just recommended if you have it.

GET /social/statistics/:user_id/:username

  • Get statistics and history for a blurblog.

Tips

  • The username url parameter is optional. It's just recommended if you have it.
feed management

POST /reader/add_url

  • Add a feed by its URL. Can be either the RSS feed or the website itself.
Parameter Description Default Example
url Required URL of website or RSS feed. http://blog.newsblur.com
folder Optional Folder to place feed in. Omit to use top level. [Top Level] Blogs

Tips

  • If you want to just show the Add Site dialog on the site, you can use this URL: http://www.newsblur.com/?url=%u

POST /reader/add_folder

  • Add a new folder.
Parameter Description Default Example
folder Required Folder name Photo-blogs Extraordinaire
parent_folder Optional Existing folder to create new folder inside of. Omit for top level. [Top Level] All Blogs

POST /reader/move_feed_to_folder

  • Move a feed into a different folder.
Parameter Description Default Example
feed_id Required Feed id. 12
in_folder Required Current folder the feed is in. Necessary to disambiguate if a feed is in multiple folders. Blogs
to_folder Required Folder the feed is going into. Tumblrs

Tips

  • Leave folder names blank to specify Top Level.

POST /reader/move_folder_to_folder

  • Move a folder into a different folder.
Parameter Description Default Example
folder_name Required Name of folder being moved. Tumblrs
in_folder Required Current folder the folder is in. Necessary to disambiguate if a folder name is in multiple folders. (Please don't let this happen.) Blogs
to_folder Required New folder the existing folder is going into. Daily Blogs

Tips

  • Leave folder names blank to specify Top Level.

POST /reader/rename_feed

  • Rename a feed title. Only the current user will see the new title.
Parameter Description Default Example
feed_title Required New feed title. NYTimes
feed_id Required Feed id of the feed to be renamed. 42

POST /reader/delete_feed

  • Unsubscribe from a feed. Removes it from the folder.
  • Set the in_folder parameter to remove a feed from the correct folder, in case the user is subscribed to the feed in multiple folders.
Parameter Description Default Example
feed_id Required Feed id of feed to remove. 42
in_folder Optional Name of folder the feed is in. News

POST /reader/rename_folder

  • Rename a folder.
Parameter Description Default Example
folder_to_rename Required Original folder name. Photoblogs
new_folder_name Required New folder name. East Coast Photoblogs
in_folder Required Name of parent folder, used to find the folder. Blogs

POST /reader/delete_folder

  • Delete a folder and unsubscribe from all feeds inside.
Parameter Description Default Example
folder_to_delete Required Name of folder to delete. Photoblogs
in_folder Optional Name of parent folder, used to find the folder. Omit if folder is top level. Blogs
feed_id Optional List of feed ids in the folder that's being deleted. These feeds also get removed. feed_id=12&feed_id=24

POST /reader/save_feed_order

  • Reorder feeds and move them around between folders.
  • The entire folder structure needs to be serialized.
Parameter Description Default Example
folders Required Object with folders and feed ids. [12, 24, 36,
{'Blogs': [56, 67, 78,
{'Photoblogs': [42]}]}]

POST /reader/save_search

  • Add a new saved search feed, which is a shortcut to a search query on a specific feed.
Parameter Description Default Example
feed_id Required A single feed id of feed to search. 42
query Required Search for a keyword or phrase in the feed. Note that only premium users can search feeds. pizza

POST /reader/delete_search

  • Deletes a saved search feed.
Parameter Description Default Example
feed_id Required A single feed id of feed to search. 42
query Required The query originally used to save the search. pizza
intelligence classifiers

GET /classifier/:id

  • Get the intelligence classifiers for a user's site.
  • Only includes the user's own classifiers. Use /reader/feeds_trainer for popular classifiers.

Tips

  • All of this data is attached to a feed when called with /reader/feed/:id.
  • After loading a feed, there is no need to explicitly call this endpoint, unless the feed has not yet been fetched.

POST /classifier/save

  • Save intelligence classifiers (tags, titles, authors, and the feed) for a feed.
Parameter Description Default Example
feed_id Required ID of feed for the classifier. 42
like_[TYPE] Optional Positive score for TYPE <- [tag, author, title, feed] like_author=
Samuel Clay
dislike_[TYPE] Optional Negative score for TYPE <- [tag, author, title, feed] dislike_title=
New York Yankees
remove_like_[TYPE] Optional Clear score for a classifier. remove_like_author=
Samuel Clay
remove_dislike_[TYPE] Optional Functionally the same as remove_like_[TYPE]. remove_dislike_title=
New York Yankees

Tips

  • The endpoint is far different from all other endpoints. It takes a variety of param keys.
  • You can send a list for any of the keys. like_tag[]=tech&like_tag[]=mobile
import/export

GET /import/opml_export

  • Download a backup of feeds and folders as an OPML file.
  • Contains folders and feeds in XML; useful for importing in another RSS reader.

POST /import/opml_upload

  • Upload an OPML file.
Parameter Description Default Example
file Required The OPML file in XML format.
API Guidelines and Terms of Service

NewsBlur's API allows users to retrieve their feeds, feed counts, feed icons, feed statistics, and individual feed stories. No API key is required, but you are required to authenticate before using any of the API endpoints. Please be considerate, and don't hammer our servers.

If your project or application allows users to interact with data from NewsBlur, you must cite NewsBlur as the source of your data.

You may use the API commercially, by which we mean you may charge people money to use your project which itself uses the API. You may not, however, sell advertising against any data retrieved from NewsBlur's API. Essentially, you can charge money for your application or service, but not wrap NewsBlur in advertisements.

We reserve the right to revise these guidelines. If you violate the spirit of these terms, expect to be blocked without advance warning.