{% extends 'base.html' %} {% block bodyclass %}NB-static NB-static-api{% endblock %} {% block content %}
The NewsBlur API
{# ========= #} {# = Feeds = #} {# ========= #}
API Table of Contents
Feeds
/reader/feeds User's feeds, with unread counts, meta data, and optional favicons.
/reader/favicons Favicons for each of a user's feeds.
/reader/page/:id Original page from a single feed.
/reader/refresh_feeds Get latest unread counts for active feeds.
Stories
/reader/feed/:id Stories from a single feed.
/reader/starred_stories User's starred stories.
/reader/river_stories Stories from multiple feeds (River of News).
Import/Export
/import/opml_upload Upload OPML file.
/import/opml_export Download backup of feeds as an OPML file.
Feeds

GET /reader/feeds

  • Retrieve a user's list of feeds. 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. true 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

Example Response


  {
    'feeds': []
  }

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]

Example Response


  {
    'feeds': []
  }

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.

Example Response


  {#  #}
  {#  #}
  {#    #}
  {#   Proxied Page #}
  {#  #}
  {#  #}
  {#   
This is a proxied page. This is straight HTML.
 #}
  {#  #}
  {#  #}

GET /reader/refresh_feeds

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

Example Response


{
  'feeds': []
}
{# =========== #} {# = Stories = #} {# =========== #}
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

Example Response


  {
    'feeds': []
  }

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

Example Response


  {
    'feeds': []
  }

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 List of feed ids. [12, 24, 36]
page optional Page of stories, starting from 1. 1 2

Example Response


  {
    'feeds': []
  }
{# ================ #} {# = Intelligence = #} {# ================ #}
Intelligence
{# ===================== #} {# = Terms of Services = #} {# ===================== #}
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.

{% endblock content %}