The NewsBlur API

Introduction to the API

NewsBlur is an RSS feed reader with intelligence.

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.

It is a very nice thing to note that this entire API is open-source, including the implementation of the endpoints. You can find the source of the /reader/ views, /rss_feeds/ views, as well as the API definitions in YAML.

API Table of Contents

authentication

Login as an existing user.
POST /api/login
Logout the currently logged in user.
POST /api/logout
Create a new user.
POST /api/signup

feeds

Information about a feed from its address.
GET /rss_feeds/search_feed
User's feeds, with unread counts, meta data, and optional favicons.
GET /reader/feeds
Favicons for each of a user's feeds.
GET /reader/favicons
Original page from a single feed.
GET /reader/page/:id
Get latest unread counts for active feeds.
GET /reader/refresh_feeds
Get all popular and known intelligence classifiers.
GET /reader/feeds_trainer
Get statistics and history for a feed.
GET /rss_feeds/statistics/:id
Get a list of feeds that contain a phrase.
GET /rss_feeds/feed_autocomplete

stories

Stories from a single feed.
GET /reader/feed/:id
User's starred stories.
GET /reader/starred_stories
Stories from multiple feeds (River of News).
GET /reader/river_stories
Mark a story as read.
POST /reader/mark_story_as_read
Mark stories from multiple feeds as read.
POST /reader/mark_feed_stories_as_read
Mark a story as unread.
POST /reader/mark_story_as_unread
Mark a story as starred (saved).
POST /reader/mark_story_as_starred
Mark a list of feeds as read.
POST /reader/mark_feed_as_read
Mark all stories from all feeds as read.
POST /reader/mark_all_as_read

feed management

Add a feed by its URL (RSS feed or website).
POST /reader/add_url
Add a new folder.
POST /reader/add_folder
Move a feed into a different folder.
POST /reader/move_feed_to_folder
Move a folder into a different folder.
POST /reader/move_folder_to_folder
Rename a feed title.
POST /reader/rename_feed
Unsubscribe from a feed.
POST /reader/delete_feed
Rename a folder.
POST /reader/rename_folder
Delete a folder and unsubscribe from all feeds inside.
POST /reader/delete_folder
Reorder feeds and move them around between folders.
POST /reader/save_feed_order

intelligence classifiers

Get the intelligence classifiers for a user's site.
GET /classifier/:id
Save intelligence classifiers for a feed.
POST /classifier/save

import/export

Download backup of feeds as an OPML file.
GET /import/opml_export
Upload an OPML file.
POST /import/opml_upload

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	Example
username	Required Username	`samuelclay`
password	Optional Password	`new$blur`
email	Optional Email address	`samuel@ofbrooklyn.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
feeds	Optional Array of feed ids. Leave empty to retrieve all active (enabled) feeds.		`[1, 2, 3]`

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.		`[1, 2, 3]`

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`

`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`

`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.		`[12, 24, 36]`
page	Optional Page of stories, starting from 1.	`1`	`2`
read_stories_count	Optional An optimization used to skip a set number of stories that are guaranteed to be read. Pass in the number of stories that have been read from this series. If your page >= 2, you should probably have some read stories from the first page.	`0`	`12`

`POST /reader/mark_story_as_read`

Mark stories as read.
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.		`[12, 24, 36]`
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`

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_story_as_unread`

Mark a story as unread.

Parameter	Description	Default	Example
story_id	Required Story id to mark unread.		`http://www.ofbrooklyn.com/story-title`
feed_id	Required Feed id that the story is from.		`42`

`POST /reader/mark_story_as_starred`

Mark a story as starred (saved).

Parameter	Description	Default	Example
story_id	Required Story id to save.		`64`
feed_id	Required Feed id that the story is from.		`42`

`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.		`[12, 24, 36]`

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.

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`

`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	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	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	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	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.	`[12, 24, 36]`

`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]}]}]`

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