FreshRSS - Google Reader compatible API implementation

See Mobile access for general aspects of API access.

See also the page about our Fever compatible API for another possibility (less powerful).

RSS clients

There are many RSS clients that support the Fever API, but they might understand the 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 greader.php address (e.g. https://freshrss.example.net/api/greader.php).

Compatible clients

  1. On the same FreshRSS API page, note the address given under “Your API address”, like https://freshrss.example.net/api/greader.php
  2. Type the API address in a client, together with your FreshRSS username, and the corresponding special API password.
App Platform License
News+ with News+ Google Reader extension Android Closed Source (Free), partially open source
FeedMe 3.5.3+ Android Closed Source (Free)
EasyRSS Android GPLv3 (F-Droid)
Readrops Android GPLv3
Fluent Reader Lite Android, iOS BSD-3
Read You Android GPLv3
FocusReader Android Closed Source(Free)
Newsflash Linux GPLv3
lire iOS, macOS Closed Source
Newsboat 2.24+ Linux MIT
Vienna RSS macOS Apache-2.0
Reeder macOS, iOS Closed Source
FreshRSS-Notify Firefox Open Source

ℹ️ See a better table of compatible clients in our main Readme.

Google Reader compatible API

Examples of basic queries:

# Initial login, using API password (Email and Passwd can be given either as GET, or POST - better)
curl 'https://freshrss.example.net/api/greader.php/accounts/ClientLogin?Email=alice&Passwd=Abcdef123456'
SID=alice/8e6845e089457af25303abc6f53356eb60bdb5f8
Auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8

# Examples of read-only requests
curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
  'https://freshrss.example.net/api/greader.php/reader/api/0/subscription/list?output=json'

curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
  'https://freshrss.example.net/api/greader.php/reader/api/0/unread-count?output=json'

curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
  'https://freshrss.example.net/api/greader.php/reader/api/0/tag/list?output=json'

# Retrieve a token for requests making modifications
curl -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
  'https://freshrss.example.net/api/greader.php/reader/api/0/token'
8e6845e089457af25303abc6f53356eb60bdb5f8ZZZZZZZZZZZZZZZZZ

# Get articles, piped to jq for easier JSON reading
curl -s -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
  'https://freshrss.example.net/api/greader.php/reader/api/0/stream/contents/reading-list' | jq .

# Unsubscribe from a feed
curl -H "Authorization:GoogleLogin auth=alice/8e6845e089457af25303abc6f53356eb60bdb5f8" \
  -d 'ac=unsubscribe&s=feed/52' 'https://freshrss.example.net/api/greader.php/reader/api/0/subscription/edit'

API documentation from the original Google Reader

API documentation from other compatible servers

Synchronisation strategy

ℹ️ If you are maintaining a client or planning to develop a new one, please read carefully the following pieces of advice, as many clients start by having a very inneficient synchronisation strategy.