Reader API
The Reader API just supports saving new documents to Reader. We will add more endpoints in the near future. If you have any questions, please reach out :)
Authentication
Set a header with key "Authorization" and value: "Token XXX" where XXX is your
Readwise
access token. You (or your users) can get that from here: readwise.io/access_token
If you want to check that a token is valid, just make a GET request to
https://readwise.io/api/v2/auth/
with the above header.
You should receive a 204
response.
Document CREATE
Request: POST
to https://readwise.io/api/v3/save/
Parameters: A JSON object with the following keys:
Key | Type | Description | Required |
---|---|---|---|
url | string | The document's unique URL. If you don't have one, you can provide a made up value such as https://yourapp.com#document1 |
yes |
html | string | The document's content, in valid html (see examples). If you don't provide this, we will try to scrape the URL you provided to fetch html from the open web. | no |
should_clean_html | boolean | Only valid when html is provided. Pass true to have us automatically clean the html and parse the metadata (title/author) of the document for you. By default, this option is false . |
no |
title | string | The document's title, it will overwrite the original title of the document | no |
author | string | The document's author, it will overwrite the original author (if found during the parsing step) | no |
summary | string | Summary of the document | no |
published_date | date | A datetime representing when the document was published in the ISO 8601
format;
default timezone is UTC. Example: "2020-07-14T20:11:24+00:00" |
no |
image_url | string | An image URL to use as cover image | no |
location | string | One of: new , later , archive or feed . Default
is
new .Represents the initial location of the document (previously called triage_status ).
Note: if you try to use a location the user doesn't have enabled in their settings, this value will be set to their default location.
|
no |
saved_using | string | This value represents the source of the document | no |
tags | list | A list of strings containing tags, example: ["tag1", "tag2"] |
no |
Response:
- Status code:
201
or200
if document already exist - Created document details:
{
"id": "0000ffff2222eeee3333dddd4444",
"url": "https://read.readwise.io/new/read/0000ffff2222eeee3333dddd4444",
}
Usage/Examples:
- JavaScript
$.ajax({
url: 'https://readwise.io/api/v3/save/',
type: 'POST',
contentType: 'application/json',
beforeSend: function (xhr) {
xhr.setRequestHeader('Authorization', 'Token XXX');
},
data: JSON.stringify({
"url": "https://example.com/article/",
"html": "<div><h1>This article is awesome</h1><p>content here!</p></div>"
"tags": ["tag1", "tag2"]
}),
success: function (result) {console.log(result)},
error: function (error) {console.log(error)},
});
import requests
requests.post(
url="https://readwise.io/api/v3/save/",
headers={"Authorization": "Token XXX"},
json={
"url": "https://example.com/article/",
# No html is provided, so the url will be scraped to get the document's content.
"tags": ["tag3", "tag4"]
}
)
$ curl -v https://readwise.io/api/v3/save/ -H "Authorization: Token XXX" -X POST -d '{"url": "https://example.com/article/"}' -H "Content-Type: application/json"
Rate Limiting
The default base rate is 20 requests per minute.
You can check Retry-After
header in the 429 response to get the number
of seconds to wait
for.