Fever API implementation #

See Mobile access for general aspects of API access. Additionally page about our Google Reader compatible API for another possibility.

RSS clients #

There are many RSS clients that support the Fever API, but they seem to understand the Fever API a bit differently. If your favourite client doesn’t work properly with this API, please create an issue and we’ll have a look. But we can only do that for free clients.

Usage & Authentication #

Before you can start using this API, you have to enable and setup API access, which is documented here, and then reset the user’s API password.

Then point your mobile application to the fever.php address (e.g. https://freshrss.example.net/api/fever.php).

Compatible clients #

App Platform License
Fluent Reader Windows, Linux, macOS BSD-3-Clause
Fluent Reader lite Android, iOS BSD-3-Clause
Read You Android GPLv3
Fiery Feeds iOS Closed Source
Newsflash Linux GPLv3
Unread iOS Closed Source
Reeder Classic iOS Closed Source
ReadKit macOS Closed Source
FreshRSS Python API Client Python GPLv3

Features #

The following features are implemented:

The following features are not supported:

Testing and debugging #

If this API does not work as expected in your RSS reader, you can test it manually with a tool like Postman.

Configure a POST request to the URL https://freshrss.example.net/api/fever.php?api which should give you the result:

{
	"api_version": 3,
	"auth": 0
}

Great, the base setup seems to work!

Now lets try an authenticated call. Fever uses an api_key, which is the MD5 hash of "$username:$apiPassword". Assuming the user is kevin and the password freshrss, here is a command-line example to compute the resulting api_key

api_key=`echo -n "kevin:freshrss" | md5sum | cut -d' ' -f1`

Add a body to your POST request encoded as form-data and one key named api_key with the value your-password-hash:

curl -s -F "api_key=$api_key" 'https://freshrss.example.net/api/fever.php?api'

This should give:

{
	"api_version": 3,
	"auth": 1,
	"last_refreshed_on_time": "1520013061"
}

Perfect, you’re now authenticated and you can start testing the more advanced features. To do so, change the URL and append the possible API actions to your request parameters. Please refer to the original Fever documentation (also mirrored below) for more information.

Some basic calls are:

Replace some_id with a real ID from your freshrss_username_entry database.

Debugging #

If nothing helps and your client is still misbehaving, you can add the following lines to the beginning of the fever.api file to determine the cause of the problems:

file_put_contents(__DIR__ . '/fever.log', $_SERVER['HTTP_USER_AGENT'] . ': ' . json_encode($_REQUEST) . PHP_EOL, FILE_APPEND);

Then use your RSS client to query the API and afterwards check the file fever.log.

Official Fever API reference (mirrored) #

The original Fever API documentation used to live at https://feedafever.com/api but is no longer online. As the archived copy may itself disappear over time, its content is mirrored below (converted from HTML to Markdown) for reference, with only the heading levels adjusted to fit this page.

API Public Beta #

Fever 1.14 introduces the new Fever API. This API is in public beta and currently supports basic syncing and consuming of content. A subsequent update will allow for adding, editing and deleting feeds and groups. The API’s primary focus is maintaining a local cache of the data in a remote Fever installation.

I am soliciting feedback from interested developers and as such the beta API may expand to reflect that feedback. The current API is incomplete but stable. Existing features may be expanded on but will not be removed or modified. New features may be added.

Authentication #

Without further ado, the Fever API endpoint URL looks like:

http://yourdomain.com/fever/?api

All requests must be authenticated with a POSTed api_key. The value of api_key should be the md5 checksum of the Fever accounts email address and password concatenated with a colon. An example of a valid value for api_key using PHP’s native md5() function:

$email  = 'you@yourdomain.com';
$pass   = 'b3stp4s4wd3v4';
$api_key = md5($email.':'.$pass);

A user may specify that https be used to connect to their Fever installation for additional security but you should not assume that all Fever installations support https.

The default response is a JSON object containing two members:

The API can also return XML by passing xml as the optional value of the api argument like so:

http://yourdomain.com/fever/?api=xml

The top level XML element is named response.

The response to each successfully authenticated request will have auth set to 1 and include at least one additional member:

Read #

When reading from the Fever API you add arguments to the query string of the API endpoint URL. If you attempt to POST these arguments (and their optional values) Fever will not recognize the request.

Groups # 

http://yourdomain.com/fever/?api&groups

A request with the groups argument will return two additional members:

A group object has the following members:

The feeds_group object is documented under “Feeds/Groups Relationships.”

The “Kindling” super group is not included in this response and is composed of all feeds with an is_spark equal to 0. The “Sparks” super group is not included in this response and is composed of all feeds with an is_spark equal to 1.

Feeds # 

http://yourdomain.com/fever/?api&feeds

A request with the feeds argument will return two additional members:

A feed object has the following members:

The feeds_group object is documented under “Feeds/Groups Relationships.”

The “All Items” super feed is not included in this response and is composed of all items from all feeds that belong to a given group. For the “Kindling” super group and all user created groups the items should be limited to feeds with an is_spark equal to 0. For the “Sparks” super group the items should be limited to feeds with an is_spark equal to 1.

Feeds/Groups Relationships #

A request with either the groups or feeds arguments will return an additional member:

A feeds_group object has the following members:

Favicons # 

http://yourdomain.com/fever/?api&favicons

A request with the favicons argument will return one additional member:

A favicon object has the following members:

An example data value:

image/gif;base64,R0lGODlhAQABAIAAAObm5gAAACH5BAEAAAAALAAAAAABAAEAAAICRAEAOw==

The data member of a favicon object can be used with the data: protocol to embed an image in CSS or HTML. A PHP/HTML example:

echo '<img src="data:'.$favicon['data'].'">';

Items # 

http://yourdomain.com/fever/?api&items

A request with the items argument will return two additional members:

An item object has the following members:

Most servers won’t have enough memory allocated to PHP to dump all items at once. Three optional arguments control determine the items included in the response.

http://yourdomain.com/fever/?api&links

A request with the links argument will return one additional member:

A link object has the following members:

When requesting hot links you can control the range and offset by specifying a length of days for each as well as a page to fetch additional hot links. A request with just the links argument is equivalent to:

http://yourdomain.com/fever/?api&links&offset=0&range=7&page=1

Or the first page (page=1) of Hot links for the past week (range=7) starting now (offset=0).

Fever calculates Hot link temperatures in real-time. The API assumes you have an up-to-date local cache of items, feeds and favicons with which to construct a meaningful Hot view. Because they are ephemeral Hot links should not be cached in the same relational manner as items, feeds, groups and favicons.

Because Fever saves items and not individual links you can only “save” a Hot link when is_item equals 1.

Sync #

The unread_item_ids and saved_item_ids arguments can be used to keep your local cache synced with the remote Fever installation.

http://yourdomain.com/fever/?api&unread_item_ids

A request with the unread_item_ids argument will return one additional member:

http://yourdomain.com/fever/?api&saved_item_ids

A request with the saved_item_ids argument will return one additional member:

One of these members will be returned as appropriate when marking an item as read, unread, saved, or unsaved and when marking a feed or group as read.

Because groups and feeds will be limited in number compared to items, they should be synced by comparing an array of locally cached feed or group ids to an array of feed or group ids returned by their respective API request.

Write #

The public beta of the API does not provide a way to add, edit or delete feeds or groups but you can mark items, feeds and groups as read and save or unsave items. You can also unread recently read items. When writing to the Fever API you add arguments to the POST data you submit to the API endpoint URL.

Adding unread_recently_read=1 to your POST data will mark recently read items as unread.

You can update an individual item by adding the following three arguments to your POST data:

Marking a feed or group as read is similar but requires one additional argument to prevent marking new, unreceived items as read:

You can mark the “Kindling” super group (and the “Sparks” super group) as read by adding the following four arguments to your POST data:

Similarly you can mark just the “Sparks” super group as read by adding the following four arguments to your POST data:

Fever, its website and all related files are copyright © 2008-2023 Shaun Inman.

Credits #

This plugin was inspired by the tinytinyrss-fever-plugin.