mirror of
https://github.com/samuelclay/NewsBlur.git
synced 2025-08-05 16:58:59 +00:00
333 lines
No EOL
8.8 KiB
HTML
333 lines
No EOL
8.8 KiB
HTML
{% extends 'base.html' %}
|
|
|
|
{% block bodyclass %}NB-static NB-static-api{% endblock %}
|
|
|
|
{% block content %}
|
|
|
|
<div class="NB-static-title">
|
|
The NewsBlur API
|
|
</div>
|
|
|
|
|
|
{# ========= #}
|
|
{# = Feeds = #}
|
|
{# ========= #}
|
|
|
|
<div class="NB-module">
|
|
<h5 class="NB-module-title">API Table of Contents</h5>
|
|
<div class="NB-module-content">
|
|
<table class="toc">
|
|
<tr>
|
|
<th colspan="2">Feeds</th>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#feeds"><code>/reader/feeds</code></a></td>
|
|
<td>User's feeds, with unread counts, meta data, and optional favicons.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#favicons"><code>/reader/favicons</code></a></td>
|
|
<td>Favicons for each of a user's feeds.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#page"><code>/reader/page/:id</code></a></td>
|
|
<td>Original page from a single feed.</td>
|
|
</tr>
|
|
<tr>
|
|
<th colspan="2">Stories</th>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#feed"><code>/reader/feed/:id</code></a></td>
|
|
<td>Stories from a single feed.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#starred_stories"><code>/reader/starred_stories</code></a></td>
|
|
<td>User's starred stories.</td>
|
|
</tr>
|
|
<tr>
|
|
<td><a href="#river_stories"><code>/reader/river_stories</code></a></td>
|
|
<td>Stories from multiple feeds (River of News).</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="NB-module">
|
|
<h5 class="NB-module-title">Feeds</h5>
|
|
<div class="NB-module-content">
|
|
|
|
|
|
<h3><tt>GET /reader/feeds</tt></h3>
|
|
<a class="NB-anchor" name="feeds"></a>
|
|
|
|
<ul>
|
|
<li>Retrieve a user's list of feeds. Includes the 3 unread counts (positive, neutral,
|
|
negative), as well as optional favicons.</li>
|
|
</ul>
|
|
|
|
<table>
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Description</th>
|
|
<th>Default</th>
|
|
<th>Example</th>
|
|
</tr>
|
|
<tr>
|
|
<td>include_favicons</td>
|
|
<td><span class="optional">Optional</span> Include
|
|
favicons inline. Since they can be time consuming to download, you can optionally
|
|
turn them off. Use <tt>/api/v1/feeds/favicons/</tt> to retrieve the favicons in a
|
|
separate request.</td>
|
|
<td><code>true</code></td>
|
|
<td><code>true/false</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>flat</td>
|
|
<td><span class="optional">Optional</span> Returns a flat folder structure instead of nested folders. Useful when displaying all folders in a single depth without recursive descent.</td>
|
|
<td><code>false</code></td>
|
|
<td><code>true/false</code></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>Example Response</h4>
|
|
|
|
<pre><code>
|
|
{
|
|
'feeds': []
|
|
}
|
|
</code></pre>
|
|
|
|
<h4>Tips</h4>
|
|
|
|
<ul>
|
|
<li>Use <code>/reader/refresh_feeds</code> to get updated unread counts.</li>
|
|
<li>Turn off <code>include_favicons</code> if you can either cache favicons or can
|
|
wait to fetch them.</li>
|
|
</ul>
|
|
|
|
|
|
|
|
<h3><tt>GET /reader/favicons</tt></h3>
|
|
<a class="NB-anchor" name="favicons"> </a>
|
|
|
|
<ul>
|
|
<li>Retrieve a list of favicons for a list of feeds. Used when combined with
|
|
<tt>/reader/feeds</tt> and <tt>include_favicons=false</tt>, so the
|
|
feeds request contains far less data. Useful for mobile devices, but requires a
|
|
second request.</li>
|
|
</ul>
|
|
|
|
<table>
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Description</th>
|
|
<th>Default</th>
|
|
<th>Example</th>
|
|
</tr>
|
|
<tr>
|
|
<td>feeds</td>
|
|
<td><span class="optional">OPTIONAL</span> Array of feed ids. Leave empty to retrieve all active (enabled) feeds.</td>
|
|
<td></td>
|
|
<td><code>[1, 2, 3]</code></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>Example Response</h4>
|
|
|
|
<pre><code>
|
|
{
|
|
'feeds': []
|
|
}
|
|
</code></pre>
|
|
|
|
<h4>Tips</h4>
|
|
|
|
<ul>
|
|
<li>To use inline data images, you can use this syntax:
|
|
<pre><code>
|
|
<img src="data:image/png;base64,[IMAGE_DATA_STRING]" />
|
|
</code></pre>
|
|
</li>
|
|
</ul>
|
|
|
|
|
|
<h3><tt>GET /reader/page/:id</tt></h3>
|
|
<a class="NB-anchor" name="feed_page"> </a>
|
|
|
|
<ul>
|
|
<li>Retrieve the original page from a single feed.</li>
|
|
</ul>
|
|
|
|
<h4>Example Response</h4>
|
|
|
|
<pre><code>
|
|
{# <html> #}
|
|
{# <head> #}
|
|
{# <base href="http://www.newsblur.com" /> #}
|
|
{# <title>Proxied Page</title> #}
|
|
{# </head> #}
|
|
{# <body> #}
|
|
{# <p>This is a proxied page. This is straight HTML.</p> #}
|
|
{# </body> #}
|
|
{# </html> #}
|
|
</code></pre>
|
|
|
|
</div>
|
|
</div>
|
|
|
|
|
|
{# =========== #}
|
|
{# = Stories = #}
|
|
{# =========== #}
|
|
|
|
|
|
<div class="NB-module">
|
|
<h5 class="NB-module-title">Stories</h5>
|
|
<div class="NB-module-content">
|
|
|
|
|
|
<h3><tt>GET /reader/feed/:id</tt></h3>
|
|
<a class="NB-anchor" name="feed"> </a>
|
|
|
|
<ul>
|
|
<li>Retrieve stories from a single feed.</li>
|
|
</ul>
|
|
|
|
<table>
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Description</th>
|
|
<th>Default</th>
|
|
<th>Example</th>
|
|
</tr>
|
|
<tr>
|
|
<td>page</td>
|
|
<td><span class="optional">optional</span> Page of stories, starting from 1.</td>
|
|
<td><code>1</code></td>
|
|
<td><code>2</code></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>Example Response</h4>
|
|
|
|
<pre><code>
|
|
{
|
|
'feeds': []
|
|
}
|
|
</code></pre>
|
|
|
|
|
|
|
|
<h3><tt>GET /reader/starred_stories</tt></h3>
|
|
<a class="NB-anchor" name="starred_stories"></a>
|
|
|
|
<ul>
|
|
<li>Retrieve a user's starred stories.</li>
|
|
</ul>
|
|
|
|
<table>
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Description</th>
|
|
<th>Default</th>
|
|
<th>Example</th>
|
|
</tr>
|
|
<tr>
|
|
<td>page</td>
|
|
<td><span class="optional">optional</span> Page of starred stories, starting from 1.</td>
|
|
<td><code>1</code></td>
|
|
<td><code>2</code></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>Example Response</h4>
|
|
|
|
<pre><code>
|
|
{
|
|
'feeds': []
|
|
}
|
|
</code></pre>
|
|
|
|
|
|
<h3><tt>GET /reader/river_stories</tt></h3>
|
|
<a class="NB-anchor" name="river_stories"> </a>
|
|
|
|
<ul>
|
|
<li>Retrieve stories from a collection of feeds. This is known as the River of News.</li>
|
|
<li>Stories are ordered in reverse chronological order.</li>
|
|
</ul>
|
|
|
|
<table>
|
|
<tr>
|
|
<th>Parameter</th>
|
|
<th>Description</th>
|
|
<th>Default</th>
|
|
<th>Example</th>
|
|
</tr>
|
|
<tr>
|
|
<td>feeds</td>
|
|
<td><span class="required">required</span> List of feed ids.</td>
|
|
<td></td>
|
|
<td><code>[12, 24, 36]</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td>page</td>
|
|
<td><span class="optional">optional</span> Page of stories, starting from 1.</td>
|
|
<td><code>1</code></td>
|
|
<td><code>2</code></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h4>Example Response</h4>
|
|
|
|
<pre><code>
|
|
{
|
|
'feeds': []
|
|
}
|
|
</code></pre>
|
|
|
|
|
|
</div>
|
|
</div>
|
|
|
|
|
|
{# ================ #}
|
|
{# = Intelligence = #}
|
|
{# ================ #}
|
|
|
|
<div class="NB-module">
|
|
<h5 class="NB-module-title">Intelligence</h5>
|
|
<div class="NB-module-content">
|
|
|
|
|
|
|
|
</div>
|
|
</div>
|
|
|
|
|
|
{# ===================== #}
|
|
{# = Terms of Services = #}
|
|
{# ===================== #}
|
|
|
|
|
|
<div class="NB-module">
|
|
<h5 class="NB-module-title">API Guidelines and Terms of Service</h5>
|
|
<div class="NB-module-content">
|
|
<p>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.</p>
|
|
|
|
<p>If your project or application allows users to interact with data from NewsBlur,
|
|
you must cite NewsBlur as the source of your data.</p>
|
|
|
|
<p>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.</p>
|
|
|
|
<p><i>We reserve the right to revise these guidelines. If you violate the spirit of
|
|
these terms, expect to be blocked without advance warning.</i></p>
|
|
</div>
|
|
</div>
|
|
|
|
{% endblock content %} |