• Social features
• Tagging items
• OAuth

• Feeddler
• Feeddler Pro
• Feedoo
• RssReader

• gReader
• gReader Pro
• D7 Reader
• D7 Reader Pro
• The Old Reader (unofficial, beta)
• Listener Launcher
• Wizz Widget
• NewsJet
• Daily Feed

• Old Reader
• Rss Reader
• NewsSpot

• ThOR
• Gravity (Beta Support)

• inboxN.com
• Oxnt (send to Kindle)
• Updatified

• Liferea (Linux)
• FeedSpider (WebOS)
• FireReader (Firefox OS)
• yTOR (Windows)

• tornexto (go to next item in a folder)

• PHP (by zelenin)
• Ruby (by ianzy)

You are welcome to improve documentation, please feel free to send us pull requests with your adjustments.

If you find any bugs or feel that something is not working as expected, please create a github issue or contact us at [email protected].

Current API tries to mimic the unofficial Google Reader API.

Please note that even though you can use API both via http and https, we highly encourage you to use https for security reasons.

• Currently only json format is supported
• We use BSON ObjectId for user, item, subscription identifiers (example: 00157a17b192950b65be3791)
• We also use ObjectId in Stream Ids instead of URL (example: feed/00157a17b192950b65be3791)
• All user ids are replaced by - in state/label strings (examples: user/-/state/com.google/reading-list, user/-/label/Folder)

All requests you will be sending to the API should be authenticated by a token.

Please note that The Old Reader allows users to sign in via OAuth (Google or Facebook), but the only way to get an API token for a now is to set password in settings and use it for authentication.

Sample request:

curl -d "client=YourAppName&accountType=HOSTED_OR_GOOGLE&service=reader&[email protected]&Passwd=..." https://theoldreader.com/accounts/ClientLogin

Sample response:

SID=none
LSID=none
Auth=LyTEJPvTJiSPrCxLu46d

Please note that you can also get a token by requesting following url: /reader/api/0/accounts/ClientLogin

Also you might want to add output=json to POST parameters for corresponding result.

Include Authorization: GoogleLogin auth=TOKEN HTTP header in all your requests. For example:

Authorization: GoogleLogin auth=LyTEJPvTJiSPrCxLu46d

All errors have following format:

XML:

<?xml version="1.0" encoding="UTF-8"?>
<errors type="array">
  <error>XML output currently is not supported</error>
</errors>

JSON:

{
	errors: [
		"Temporary unavailable, please try later"
	]
}

After a couple unsuccessful requests you might try to obtain current The Old Reader status:

GET https://theoldreader.com/reader/api/0/status?output=json

Everything is fine:

> curl https://theoldreader.com/reader/api/0/status?output=json
{"status":"up"}

Something is wrong:

> curl https://theoldreader.com/reader/api/0/status?output=json
{"status":"down","description":"Database issues","redirect":"http://status.theoldreader.com"}

GET https://theoldreader.com/reader/api/0/token

> curl https://theoldreader.com/reader/api/0/token -H "Authorization: GoogleLogin auth=LyTEJPvTJiSPrCxLu46d"
LyTEJPvTJiSPrCxLu46d

Added for compatibility.

GET https://theoldreader.com/reader/api/0/user-info?output=json

> curl https://theoldreader.com/reader/api/0/user-info?output=json -H "Authorization: GoogleLogin auth=LyTEJPvTJiSPrCxLu46d"
{"userId":"00157a17b192950b65be3791","userName":"Test","userProfileId":"00157a17b192950b65be3791","userEmail":"[email protected]","isBloggerUser":false,"signupTimeSec":1370709105,"isMultiLoginEnabled":false}

GET https://theoldreader.com/reader/api/0/preference/list?output=json

Added for compatibility.

GET https://theoldreader.com/reader/api/0/friend/list?output=json

Added for compatibility for now. Will be used for The Old Reader social features.

GET https://theoldreader.com/reader/api/0/tag/list?output=json

Contains folder list.

GET https://theoldreader.com/reader/api/0/preference/stream/list?output=json

Contains information about subscriptions ordering for root (folders and subscriptions ordering) and user folders (subscriptions ordering).

POST https://theoldreader.com/reader/api/0/preference/stream/set

Added for compatibility.

POST https://theoldreader.com/reader/api/0/rename-tag

Parameters:

s=user/-/label/Folder
dest=user/-/label/NewFolder

POST https://theoldreader.com/reader/api/0/disable-tag

Removes folder and moves subscriptions to default folder.

Parameters:

s=user/-/label/Folder

GET https://theoldreader.com/reader/api/0/unread-count?output=json

Contains unread counts for all items (reading list), each folder and subscription.

GET https://theoldreader.com/reader/api/0/subscription/list?output=json

Each subscription contains url, htmlUrl and iconUrl.

GET https://theoldreader.com/reader/subscriptions/export

POST https://theoldreader.com/reader/api/0/subscription/quickadd?quickadd=blog.theoldreader.com

Successful response:

{"query":"blog.theoldreader.com","numResults":1,"streamId":"feed/00157a17b192950b65be3791"}

Failed response:

{"query":"blog.theoldreader.com","numResults":0,"error":"Feed was not added. You already have 129 subscriptions, your limit is 100. You should upgrade to premium."}

POST https://theoldreader.com/reader/api/0/subscription/edit

Parameters:

ac=edit

# Stream Id
s=feed/00157a17b192950b65be3791

# Change subscription title
t=Title

# Move subscription to folder with a given title
a=user/-/label/Folder

# Move subscription to default folder (no difference what r is)
r=user/-/label/Folder

POST https://theoldreader.com/reader/api/0/subscription/edit

Parameters:

ac=unsubscribe
s=feed/00157a17b192950b65be3791 # Stream Id

GET https://theoldreader.com/reader/api/0/stream/items/ids?output=json

Parameters:

Filter by stream:

# All items
s=user/-/state/com.google/reading-list

# Starred items
s=user/-/state/com.google/starred

# Read items
s=user/-/state/com.google/read

# Folder
s=user/-/label/...

# Subscription
s=feed/...

Exclude items (please note that this does not work for starred items):

# Only unread
xt=user/-/state/com.google/read

Other parameters:

n=1000 # Limit items
r=o # Reverse sorting
c=… # Continuation
nt=1371645508 # Older than
ot=1371645508 # Newer than

Please note that maximum limit is: 10000 for item ids, 1000 for item contents.

POST https://theoldreader.com/reader/api/0/stream/items/contents?output=json

Parameters:

# Item ids
i=…&i=…&i=…

# Atom output
output=atom

GET https://theoldreader.com/reader/api/0/stream/contents?output=json

Parameters:

# Same as for ids

# Atom output
output=atom

Also there is an atom feed for specific Stream Id:

GET https://theoldreader.com/reader/atom/feed/00157a17b192950b65be3791

And state:

GET https://theoldreader.com/reader/atom/user/-/state/com.google/read

And folder:

GET https://theoldreader.com/reader/atom/user/-/label/Folder

POST https://theoldreader.com/reader/api/0/mark-all-as-read

Please note that this does not work for starred items.

Parameters:

# All items
s=user/-/state/com.google/reading-list

# Folder
s=user/-/label/...

# Subscription
s=feed/...

# Older than timestamp in nanoseconds
ts=1371645508000000

POST https://theoldreader.com/reader/api/0/edit-tag

Parameters:

# Item ids
i=…&i=…&i=…

# Mark as read
a=user/-/state/com.google/read

# Mark as starred
a=user/-/state/com.google/starred

# Mark as unread
r=user/-/state/com.google/read

# Remove starred mark
r=user/-/state/com.google/starred