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

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
Original text from a story.
GET /rss_feeds/original_text
Proxied story from website.
GET /rss_feeds/original_story
User's starred stories.
GET /reader/starred_stories
Story hashes of starred stories.
GET /reader/starred_story_hashes
Stories from multiple feeds (River of News).
GET /reader/river_stories
Stories by story_hash.
GET /reader/river_stories
The story_hashes of all unread stories.
GET /reader/unread_story_hashes
Feed of previously read stories.
GET /reader/read_stories
Mark a story as read.
POST /reader/mark_story_hashes_as_read
Mark a story as read (deprecated).
POST /reader/mark_story_as_read
Mark stories from multiple feeds as read (deprecated).
POST /reader/mark_feed_stories_as_read
Mark stories from a blurblog as read (deprecated).
POST /reader/mark_social_stories_as_read
Mark a story as unread.
POST /reader/mark_story_hash_as_unread
Mark a story as starred (saved).
POST /reader/mark_story_hash_as_starred
Mark a story as unstarred (unsaved).
POST /reader/mark_story_hash_as_unstarred
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

social

Stories from multiple users (River of News).
GET /social/river_stories
Share a story with optional comments.
POST /social/share_story
Remove a shared story from user's blurblog.
POST /social/unshare_story
Lists of user profiles: followers, followings, etc.
GET /social/load_user_friends
Public profile of a user.
GET /social/profile
Private details of the current user's profile and connected services.
GET /social/load_user_profile
Saves a user's profile details.
POST /social/save_user_profile
Interactions between a user and other users.
GET /social/interactions
A user's activities.
GET /social/activities
Follow a user and subscribe to their blurblog.
POST /social/follow
Unfollow a user and unsubscribe from their blurblog.
POST /social/unfollow
Mute a user to not see thier shares or replies.
POST /social/mute_user
Un-mute a user
POST /social/unmute_user
Get the intelligence classifiers for a blurblog.
GET /social/feed_trainer
Get all public comments on a shared story.
GET /social/public_comments
Saves a reply to a comment.
POST /social/save_comment_reply
Deletes a reply.
POST /social/remove_comment_reply
Favorites a comment.
POST /social/like_comment
Un-favorites a comment.
POST /social/remove_like_comment
Search for a user by username, email, or blurblog title.
GET /social/find_friends
RSS feed for a blurblog.
GET /social/rss/:user_id/:username
Shared stories from a user's blurblog.
GET /social/stories/:user_id/:username
A user's shared stories blurblog in HTML.
GET /social/page/:user_id/:username
A user's full profile.
GET /social/settings/:user_id/:username
Get statistics and history for a blurblog.
GET /social/statistics/:user_id/:username

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
Add a new saved search feed.
POST /reader/save_search
Removes a saved search feed.
POST /reader/delete_search

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`

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

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.