Reader API Client

The Reader API client requires four pieces of credential data. A consumer key and consumer secret can be obtained from your Readability account settings page. In addition to client credentials, a user’s token key and token secret must also be used for authentication. For more information regarding auth, visit the Authentication section of the docs.

Your client key and secret can be passed to the constructor directly or set via environment variables:

Under the hood, the ReaderClient use the popular requests library. The objects returned by the ReaderClient are instances of requests.Response.

Client Documentation

class readability.ReaderClient(token_key, token_secret, base_url_template='https://www.readability.com/api/rest/v1/{}', **xargs)

Client for interacting with the Readability Reader API.

Docs can be found at http://www.readability.com/developers/api/reader.

add_bookmark(url, favorite=False, archive=False, allow_duplicates=True)

Adds given bookmark to the authenticated user.

Parameters:
  • url – URL of the article to bookmark
  • favorite – whether or not the bookmark should be favorited
  • archive – whether or not the bookmark should be archived
  • allow_duplicates – whether or not to allow duplicate bookmarks to be created for a given url
add_tags_to_bookmark(bookmark_id, tags)

Add tags to to a bookmark.

The identified bookmark must belong to the current user.

Parameters:
  • bookmark_id – ID of the bookmark to delete.
  • tags – Comma separated tags to be applied.
archive_bookmark(bookmark_id)

Archives given bookmark. The requested bookmark must belong to the current user.

Parameters:bookmark_id – ID of the bookmark to archive.
delete(url)

Make a HTTP DELETE request to the Readability API.

Parameters:url – The url to which to send a DELETE request.
delete_bookmark(bookmark_id)

Delete a single bookmark represented by bookmark_id.

The requested bookmark must belong to the current user.

Parameters:bookmark_id – ID of the bookmark to delete.
delete_tag_from_bookmark(bookmark_id, tag_id)

Remove a single tag from a bookmark.

The identified bookmark must belong to the current user.

Parameters:bookmark_id – ID of the bookmark to delete.
favorite_bookmark(bookmark_id)

Favorites given bookmark. The requested bookmark must belong to the current user.

Parameters:bookmark_id – ID of the bookmark to favorite.
get(url)

Make a HTTP GET request to the Reader API.

Parameters:url – url to which to make a GET request.
get_article(article_id)

Get a single article represented by article_id.

Parameters:article_id – ID of the article to retrieve.
get_bookmark(bookmark_id)

Get a single bookmark represented by bookmark_id.

The requested bookmark must belong to the current user.

Parameters:bookmark_id – ID of the bookmark to retrieve.
get_bookmark_tags(bookmark_id)

Retrieve tags that have been applied to a bookmark.

The requested bookmark must belong to the current user.

Parameters:bookmark_id – ID of the bookmark to delete.
get_bookmarks(**filters)

Get Bookmarks for the current user.

Filters:

Parameters:
  • archive – Filter Bookmarks returned by archived status.
  • favorite – Filter Bookmarks returned by favorite status.
  • domain – Filter Bookmarks returned by a domain.
  • added_since – Filter bookmarks by date added (since this date).
  • added_until – Filter bookmarks by date added (until this date).
  • opened_since – Filter bookmarks by date opened (since this date).
  • opened_until – Filter bookmarks by date opened (until this date).
  • archived_since – Filter bookmarks by date archived (since this date.)
  • archived_until – Filter bookmarks by date archived (until this date.)
  • updated_since – Filter bookmarks by date updated (since this date.)
  • updated_until – Filter bookmarks by date updated (until this date.)
  • page – What page of results to return. Default is 1.
  • per_page – How many results to return per page. Default is 20, max is 50.
  • only_deleted – Return only bookmarks that this user has deleted.
  • tags – Comma separated string of tags to filter bookmarks.
get_tag(tag_id)

Get a single tag represented by tag_id.

The requested tag must belong to the current user.

Parameters:tag_id – ID fo the tag to retrieve.
get_tags()

Get all tags belonging to the current user.

get_user()

Retrives the current user.

post(url, post_params=None)

Make a HTTP POST request to the Reader API.

Parameters:
  • url – url to which to make a POST request.
  • post_params – parameters to be sent in the request’s body.
set_read_percent_of_bookmark(bookmark_id, read_percent)

Set the read percentage of given bookmark. The requested bookmark must belong to the current user.

Parameters:
  • bookmark_id – ID of the bookmark to update.
  • read_percent – The read progress made in this article, where 1.0 means the bottom and 0.0 means the very top.
update_bookmark(bookmark_id, favorite=None, archive=None, read_percent=None)

Updates given bookmark. The requested bookmark must belong to the current user.

Parameters:
  • bookmark_id – ID of the bookmark to update.
  • (optional) (read_percent) – Whether this article is favorited or not.
  • (optional) – Whether this article is archived or not.
  • (optional) – The read progress made in this article, where 1.0 means the bottom and 0.0 means the very top.