Before using the Readability API, please read over the Terms of Service.
API Keys are available to all registered users of Readability. You will need an account for testing, so create a (free) reader account and go to Account=>Connections to create an API Key.
If you'd like access to the Readability parser directly, the Content API is available upon request. Contact us if you're interested.
All requests to the Readability service require access tokens. You can acquire an access token two ways:
OAuth Endpoints are as follows:
https://www.readability.com/api/rest/v1/oauth/authorize/https://www.readability.com/api/rest/v1/oauth/request_token/https://www.readability.com/api/rest/v1/oauth/access_token/XAuth requires a single endpoint for authorization:
https://www.readability.com/api/rest/v1/oauth/access_token/
XAuth functions just like OAuth, except it skips the authorization process. Along with the standard oauth_* signing keys,
the client sends x_auth_username, x_auth_password, and x_auth_mode (set to client_auth).
The response is an authorized access token. In most cases, you should do your best to support OAuth proper. This allows users to never have to pass their Readability
username and password into your (third-party) application, making your application, and our application, more secure.
If you are using XAuth, do not store the user's password. Use it once to retrieve an access token and discard it.
To obtain API keys, please contact support@readability.com.
There's a growing list of API Libraries available for integration in your project:
If you've written a wrapper for the Readability API, tell us about it.
The most obvious use case for the Readability API is to be able to add a bookmark into a user's queue. Here's how it's done:
POST /api/rest/v1/bookmarks Content-Type: application/x-www-form-urlencoded url=http://blog.arc90.com/2010/11/30/silence-is-golden/&favorite=1
HTTP/1.0 202 Accepted Location: /api/rest/v1/bookmarks/119 X-Article-Location: /api/rest/v1/articles/xj28dwkx
You can browse to the new bookmark at the URI returned in the Location header:
GET /api/rest/v1/bookmarks/119 HTTP/1.1
HTTP/1.1 200 OK
Date: Thu, 12 Oct 2010 20:13:58 GMT
Last-Modified: Wed, 12 Oct 2010 12:39:02 -0500
Content-Type: application/json
{
"user_id": 1,
"read_percent": "0.0",
"date_updated": "2010-10-12 13:38:33",
"favorite": true,
"article": {
"domain": "blog.arc90.com",
"title": "Silence is Golden",
"url": "http://blog.arc90.com/2010/11/30/silence-is-golden/",
"lead_image_url": null,
"author": "Tim Meaney",
"excerpt": "I’ve been building software for 15 years and continue to be…",
"direction": "ltr",
"word_count": 1094,
"date_published": "2010-11-30 00:00:00",
"dek": null,
"processed": true,
"id": "tg8if9uj"
},
"id": 119,
"date_archived": null,
"date_opened": null,
"date_added": "2010-10-12 13:38:33",
"article_href": "/api/rest/v1/articles/tg8if9uj",
"date_favorited": "2010-10-12 13:38:33",
"archive": false
}
All requests are, by default, provided as JSON. You may also pass ?format=xml in the URL to convert this into XML data to be consumed.
API data is encoded in UTF-8. You may need to convert UTF-8 for characters to appear properly.
available response representations:
available response representations:
potential faults:
| parameter | value | description |
|---|---|---|
archive | One of:
| Filter bookmarks by archived status. |
favorite | One of:
| Filter bookmarks by favorited status. |
domain | Filter bookmarks by 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). | |
favorited_since | Filter bookmarks by date favorited (since this date). | |
favorited_until | Filter bookmarks by date favorited (until this date). | |
updated_since | Filter bookmarks by date updated (since this date). | |
updated_until | Filter bookmarks by date updated (until this date). | |
order | One of:
| What to order these bookmarks by. Default is date_added descending (-date_added). |
page | For pagination, what page of the results you are on. Default is 1. | |
per_page | For pagination, how many results to return per page. Default is 20. Max is 50. | |
exclude_accessibility | One of:
| This parameter is deprecated and should no longer be used. |
only_deleted | One of:
| If only_deleted is 1, this will return the bookmark IDs that have been deleted from this user's store. This is useful for synchronization of bookmarks. Note that a deleted bookmark does not contain article information. The representation of a deleted bookmark in the bookmarks collection is described in the only deleted bookmarks representation. |
available response representations:
202 Accepted, meaning that the bookmark has been added but no guarantees are made as to whether the article proper has yet been parsed.
| parameter | value | description |
|---|---|---|
url | anyURI (required) | The URL of the article to associate the bookmark with. If it already exists in the users bookmark list, it will return a 409 with the Location header to the current bookmark. |
favorite | Whether this article is favorited or not. 1 (true) or 0 (false). | |
archive | Whether this article is archived or not. 1 (true) or 0 (false). |
| parameter | value | description |
|---|---|---|
Content-Type | string (required) |
A value of |
acceptable request representations:
| parameter | value | description |
|---|---|---|
Location | ||
X-Article-Location |
potential faults:
available response representations:
potential faults:
200 on successful update.
| parameter | value | description |
|---|---|---|
favorite | Whether this article is favorited or not. 1 (true) or 0 (false). | |
archive | Whether this article is archived or not. 1 (true) or 0 (false). | |
read_percent | The read progress made in this article, where 1.0 means the bottom and 0.0 means the very top. Expressed as a ratio of the document length, from the top of the browser window, unless the window is at the bottom. | |
date_opened | The date and time this article was last opened by the user. |
| parameter | value | description |
|---|---|---|
Content-Type | string (required) |
A value of |
acceptable request representations:
available response representations:
potential faults:
Remove a single bookmark from this user's history. NOTE: THIS IS PROBABLY NOT WHAT YOU WANT. This is particularly for the case where a user accidentally bookmarks something they have no intention of reading or supporting. In almost all cases, you'll probably want to use archive by POSTing archive=1 to this bookmark.
If you use DELETE and this months bookmarks have not yet been tallied, the site associated with this bookmark will not receive any contributions for this bookmark. Use archive! It's better.
Returns a 204 on successful remove.
potential faults:
| parameter | value | description |
|---|---|---|
since | Filter contributions by date contributed (since this date). | |
until | Filter contributions by date contributed (until this date). | |
domain | Filter contributions by domain. | |
page | For pagination, what page of the results you are on. Default is 1. | |
per_page | For pagination, how many results to return per page. Default is 20. Max is 50. |
available response representations:
potential faults:
available response representations:
potential faults:
{
"resources": {
"bookmarks": {
"description": "The Bookmarks Collection Resource",
"href": "/api/rest/v1/bookmarks"
},
"contributions": {
"description": "The Contributions Collection Resource",
"href": "/api/rest/v1/contributions"
},
}
}
{
"domain": "www.newyorker.com",
"next_page_href": null,
"author": "Tim Parks",
"url": "http://www.newyorker.com/arts/critics/atlarge/2011/04/11/110411crat_atlarge_parks?currentPage=all",
"lead_image_url": "http://www.newyorker.com/images/2011/04/11/p233/110411_r20743_p233.jpg",
"content_size": 29426,
"title": "Booted",
"excerpt": "Italian voters used to be charmed by Berlusconi’s libertine ways. Anniversaries are uplifting when you have something to c",
"direction": "ltr",
"word_count": 4291,
"content": "<div><p>[article content here]</p></div>",
"date_published": "2011-04-11 00:00:00",
"dek": "What really ails Italy?",
"processed": true,
"short_url": "http://rdd.me/47g6s8e7",
"id": "47g6s8e7"
}
{
"conditions": {
"opened_since": null,
"added_until": null,
"opened_until": null,
"archived_until": null,
"favorite": null,
"archived_since": null,
"favorited_since": null,
"user": "jdoe",
"per_page": 2,
"favorited_until": null,
"archive": null,
"added_since": null,
"order": "-date_added",
"page": 1,
"updated_since": null,
"updated_until": null
},
"meta": {
"num_pages": 38,
"page": 1,
"item_count_total": 76,
"item_count": 2
},
"bookmarks": [
{
"user_id": 1,
"read_percent": "0.0",
"date_updated": "2010-10-12 11:38:39",
"favorite": false,
"article": {
"domain": "adobe.com",
"excerpt": "This is an excerpt of the article text, 200 chars or less…",
"word_count": 3482,
"processed": true,
"id": 87,
"title": "A brief overview of the Spark architecture and component set"
"lead_image_url": "http://www.adobe.com/images/2011/04/11/p233/110411_r20743_p233.jpg",
"author": "John Smith",
"direction": "ltr",
"date_published": "2011-04-11 00:00:00",
"dek": null,
"url": "http://www.adobe.com/devnet/flex/articles/flex4_sparkintro.html"
},
"id": 76,
"date_archived": null,
"date_opened": null,
"date_added": "2010-10-12 11:38:29",
"article_href": "/api/rest/v1/articles/87/",
"date_favorited": null,
"archive": false
},
{
"user_id": 1,
"read_percent": "0.13",
"date_updated": "2010-10-12 11:04:46",
"favorite": false,
"article": {
"domain": "w3.org",
"excerpt": "This is an excerpt of the article text, 200 chars or less…",
"word_count": 3482,
"processed": true,
"id": 86,
"title": "Web Application Description Language"
"lead_image_url": null,
"author": null,
"direction": "ltr",
"date_published": null,
"dek": null,
"url": "http://www.w3.org/Submission/wadl/"
},
"id": 75,
"date_archived": null,
"date_opened": null,
"date_added": "2010-10-12 11:04:46",
"article_href": "/api/rest/v1/articles/86/",
"date_favorited": null,
"archive": false
}
]
}
{
"bookmarks": [
{
"user_id": 1,
"read_percent": "0.00",
"date_updated": "2011-12-07 13:42:06",
"favorite": true,
"article": null,
"id": 486,
"date_archived": null,
"deleted": true,
"date_opened": null,
"date_added": "2011-12-05 17:27:32",
"article_href": null,
"date_favorited": "2011-12-05 17:37:45",
"archive": false
},
{
"user_id": 1,
"read_percent": "0.00",
"date_updated": "2011-12-12 09:43:54",
"favorite": false,
"article": null,
"id": 481,
"date_archived": null,
"deleted": true,
"date_opened": null,
"date_added": "2011-02-23 00:00:00",
"article_href": null,
"date_favorited": null,
"archive": false
}
],
"meta": {
"num_pages": 1,
"page": 1,
"item_count_total": 2,
"item_count": 2
},
"conditions": {
"opened_since": null,
"favorited_since": null,
"domain": "",
"updated_until": null,
"exclude_accessibility": "",
"archived_until": null,
"favorite": null,
"opened_until": null,
"archived_since": null,
"added_until": null,
"updated_since": null,
"user": "jdoe",
"per_page": 20,
"favorited_until": null,
"order": "-date_added",
"only_deleted": 1,
"archive": null,
"added_since": null,
"page": 1
}
}
url=http%3A%2F%2Fwww.w3.org%2FSubmission%2Fwadl%2F&favorite=1&archive=0
{
"user_id": 1,
"read_percent": "0.13",
"date_updated": "2010-10-12 11:04:46",
"favorite": false,
"article": {
"domain": "www.newyorker.com",
"title": "Booted",
"url": "http://www.newyorker.com/arts/critics/atlarge/2011/04/11/110411crat_atlarge_parks?currentPage=all",
"lead_image_url": "http://www.newyorker.com/images/2011/04/11/p233/110411_r20743_p233.jpg",
"author": "Tim Parks",
"excerpt": "Italian voters used to be charmed by Berlusconi’s libertine ways. Anniversaries are uplifting when you have something to …",
"direction": "ltr",
"word_count": 4291,
"date_published": "2011-04-11 00:00:00",
"dek": "What really ails Italy?",
"processed": true,
"id": "47g6s8e7"
},
"id": 75,
"date_archived": null,
"date_opened": null,
"date_added": "2010-10-12 11:04:46",
"article_href": "/api/rest/v1/articles/86/",
"date_favorited": null,
"archive": false
}
favorite=1&archive=0&read_percent=0.2
{
"conditions": {
"domain": null,
"since": "2010-09-01",
"page": 1,
"user": "jdoe",
"per_page": 10,
"until": "2010-10-01"
},
"meta": {
"num_pages": 1,
"page": 1,
"item_count_total": 5,
"item_count": 5
},
"contributions": [
{
"date": "2010-09-01",
"contribution": "1.33",
"user": "jdoe",
"domain": "www.nytimes.com",
"num_bookmarks": 1
},
{
"date": "2010-09-01",
"contribution": "1.33",
"user": "jdoe",
"domain": "www.engadget.com",
"num_bookmarks": 1
},
{
"date": "2010-09-01",
"contribution": "1.33",
"user": "jdoe",
"domain": "paulgraham.com",
"num_bookmarks": 1
},
{
"date": "2010-09-01",
"contribution": "1.33",
"user": "jdoe",
"domain": "voices.washingtonpost.com",
"num_bookmarks": 1
},
{
"date": "2010-09-01",
"contribution": "2.67",
"user": "jdoe",
"domain": "gizmodo.com",
"num_bookmarks": 2
}
]
}
{
"username": "jdoe",
"first_name": "John",
"last_name": "Doe",
"date_joined": "2010-10-08 12:00:17",
"has_active_subscription": false,
"reading_limit": 20
}
Authentication failed or was not provided. Verify that you have sent valid credentials.