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 or 200 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)},
});

Python


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"]
    }
)

Bash


$ 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"

Document LIST

Request: GET to https://readwise.io/api/v3/list/

Parameters: Usual query params:

Key	Type	Description	Required
id	string	The document's unique id. Using this parameter it will return just one document, if found.	no
location	string	The document's location, could be one of: `new`, `later`, `shortlist`, `archive`, `feed`	no
category	string	The document's category, could be one of: `article`, `email`, `rss`, `highlight`, `note`, `pdf`, `epub`, `tweet`, `video`	no
pageCursor	string	A string returned by a previous request to this endpoint. Use it to get the next page of documents if there are too many for one request.	no