Readwise Reader API

https://readwise.io/reader_api
Admin
The Readwise Reader API allows users to programmatically save new documents to their Readwise Reader...
Tokens:6,861
Snippets:33
Trust Score:9.9
Update:1 month ago
Show doc for...
Tokens:
Raw
### Bulk Update Implementation Examples

Source: https://readwise.io/reader_api

Examples of how to perform a bulk update request using JavaScript, Python, and Bash.

```javascript
$.ajax({
  url: 'https://readwise.io/api/v3/bulk_update/',
  type: 'PATCH',
  contentType: 'application/json',
  beforeSend: function (xhr) {
    xhr.setRequestHeader('Authorization', 'Token XXX');
    },
  data: JSON.stringify({
    "updates": [
      {"id": "abc123", "location": "archive", "seen": true},
      {"id": "def456", "category": "pdf"},
      {"id": "ghi789", "tags": ["reading-list"]}
    ]
  }),
  success: function (result) {console.log(result)},
  error: function (error) {console.log(error)},
});
```

```python
import requests
requests.patch(
    url="https://readwise.io/api/v3/bulk_update/",
    headers={"Authorization": "Token XXX"},
    json={
        "updates": [
            {"id": "abc123", "location": "archive", "seen": True},
            {"id": "def456", "category": "pdf"},
            {"id": "ghi789", "tags": ["reading-list"]},
        ]
    }
)
```

```bash
$ curl -v https://readwise.io/api/v3/bulk_update/ -H "Authorization: Token XXX" -X PATCH -d '{"updates": [{"id": "abc123", "location": "archive"}, {"id": "def456", "seen": true}]}' -H "Content-Type: application/json"
```

--------------------------------

### List tags implementation

Source: https://readwise.io/reader_api

Examples for fetching the list of tags using different programming environments.

```javascript
$.ajax({
  url: 'https://readwise.io/api/v3/tags/',
  type: 'GET',
  beforeSend: function (xhr) {
    xhr.setRequestHeader('Authorization', 'Token XXX');
    },
  success: function (result) {console.log(result)},
  error: function (error) {console.log(error)},
});
```

```python
import requests
requests.get(
    url="https://readwise.io/api/v3/tags/",
    headers={"Authorization": "Token XXX"},
)
```

```bash
$ curl -v https://readwise.io/api/v3/tags/ -H "Authorization: Token XXX"
```

--------------------------------

### Create Document via API

Source: https://readwise.io/reader_api

Examples for saving a new document to Reader using various programming environments.

```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>",
    "language": "de",
    "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.
        "language": "de",
        "tags": ["tag3", "tag4"]
    }
)
```

```bash
$ curl -v https://readwise.io/api/v3/save/ -H "Authorization: Token XXX" -X POST -d '{"url": "https://example.com/article/", "language": "de"}' -H "Content-Type: application/json"
```

--------------------------------

### GET https://readwise.io/api/v2/auth/

Source: https://readwise.io/reader_api

Verifies that the provided Readwise access token is valid.

```APIDOC
## GET https://readwise.io/api/v2/auth/

### Description
Checks that a provided authentication token is valid.

### Method
GET

### Endpoint
https://readwise.io/api/v2/auth/

### Response
#### Success Response (204)
- No content returned on success.
```

--------------------------------

### GET /documents

Source: https://readwise.io/reader_api

Retrieves a list of documents from the user's library.

```APIDOC
## GET /documents

### Description
Retrieves a paginated list of documents from the Readwise Reader library.

### Method
GET

### Response
#### Success Response (200)
- **count** (integer) - Total number of documents available.
- **nextPageCursor** (string) - Cursor for the next page of results.
- **results** (array) - List of document objects.

#### Response Example
{
    "count": 2304,
    "nextPageCursor": "01gm6kjzabcd609yepjrmcgz8a",
    "results": [
        {
            "id": "01gwfvp9pyaabcdgmx14f6ha0",
            "title": "Ends and Meanings (3): Alasdair MacIntyre virtue, mortality and story in heroic societies",
            "author": "Stuart Patience",
            "category": "rss",
            "reading_progress": 0.15
        }
    ]
}
```

--------------------------------

### Update Document via API

Source: https://readwise.io/reader_api

Examples for performing a PATCH request to update document fields using various tools.

```javascript
$.ajax({
  url: 'https://readwise.io/api/v3/update/0000ffff2222eeee3333dddd4444',
  type: 'PATCH',
  contentType: 'application/json',
  beforeSend: function (xhr) {
    xhr.setRequestHeader('Authorization', 'Token XXX');
    },
  data: JSON.stringify({
    "title": "Updated title",
    "location": "new"
  }),
  success: function (result) {console.log(result)},
  error: function (error) {console.log(error)},
});
```

```python
import requests
requests.patch(
    url="https://readwise.io/api/v3/update/0000ffff2222eeee3333dddd4444",
    headers={"Authorization": "Token XXX"},
    json={
        "title": "Updated title",
        "location": "new",
    }
)
```

```bash
$ curl -v https://readwise.io/api/v3/update/0000ffff2222eeee3333dddd4444 -H "Authorization: Token XXX" -X PATCH -d '{"title": "Updated title"}' -H "Content-Type: application/json"
```

--------------------------------

### Retrieve Document List Response

Source: https://readwise.io/reader_api

Example JSON response structure returned when listing documents from the Readwise Reader API.

```json
{
    "count": 2304,
    "nextPageCursor": "01gm6kjzabcd609yepjrmcgz8a",
    "results": [
        {
            "id": "01gwfvp9pyaabcdgmx14f6ha0",
            "url": "https://readiwise.io/feed/read/01gwfvp9pyaabcdgmx14f6ha0",
            "source_url": "https://www.driverlesscrocodile.com/values/ends-and-meanings-3-alasdair-macintyre-virtue-mortality-and-story-in-heroic-societies/",
            "title": "Ends and Meanings (3): Alasdair MacIntyre virtue, mortality and story in heroic societies",
            "author": "Stuart Patience",
            "source": "Reader RSS",
            "category": "rss",
            "location": "feed",
            "tags": {},
            "site_name": "Driverless Crocodile",
            "word_count": 819,
            "reading_time": "4 mins",
            "listening_time": null,
            "created_at": "2023-03-26T21:02:51.618751+00:00",
            "updated_at": "2023-03-26T21:02:55.453827+00:00",
            "notes": "",
            "published_date": "2023-03-22",
            "summary": "Without … a place in the social order, ...",
            "image_url": "https://i0.wp.com/www.driverlesscrocodile.com/wp-content/uploads/2019/10/cropped-driverlesscrocodile-icon-e1571123201159-4.jpg?fit=32%2C32&ssl=1",
            "parent_id": null,
            "reading_progress": 0.15,
            "first_opened_at": null,
            "last_opened_at": null,
            "saved_at": "2023-03-26T21:02:51.618751+00:00",
            "last_moved_at": "2023-03-27T21:03:52.118752+00:00",
        },
        {
            "id": "01gkqtdz9xabcd5gt96khreyb",
            "url": "https://readiwise.io/new/read/01gkqtdz9xabcd5gt96khreyb",
            "source_url": "https://www.vanityfair.com/hollywood/2017/08/the-story-of-the-ducktales-theme-music",
            "title": "The Story of the DuckTales Theme, History’s Catchiest Single Minute of Music",
            "author": "Darryn King",
            "source": "Reader add from import URL",
            "category": "article",
            "location": "new",
            "tags": {},
            "site_name": "Vanity Fair",
            "word_count": 2678,
            "reading_time": "11 mins",
            "listening_time": null,
            "created_at": "2022-12-08T02:53:29.639650+00:00",
            "updated_at": "2022-12-13T20:37:42.544298+00:00",
            "published_date": "2017-08-09",
            "notes": "A sample note",
            "summary": "A woo-hoo heard around the world.",
            "image_url": "https://media.vanityfair.com/photos/598b1452f7f0a433bd4d149c/16:9/w_1280,c_limit/t-ducktales-woohoo-song.png",
            "parent_id": null,
            "reading_progress": 0.5,
            "first_opened_at": "2023-03-26T21:02:51.618751+00:00",
            "last_opened_at": "2023-03-29T21:02:51.618751+00:00",
            "saved_at": "2023-03-26T21:02:51.618751+00:00",
            "last_moved_at": "2023-03-27T21:03:52.118752+00:00",
        },
        {
            "id": "01gkqt8nbms4t698abcdvcswvf",
            "url": "https://readwise.io/new/read/01gkqt8nbms4t698abcdvcswvf",
            "source_url": "https://www.vanityfair.com/news/2022/10/covid-origins-investigation-wuhan-lab",
            "title": "COVID-19 Origins: Investigating a “Complex and Grave Situation” Inside a Wuhan Lab",
            "author": "Condé Nast",
            "source": "Reader add from import URL",
            "category": "article",
            "location": "new",
            "tags": {},
            "site_name": "Vanity Fair",
            "word_count": 9601,
            "reading_time": "37 mins",
            "listening_time": null,
            "created_at": "2022-12-08T02:50:35.662027+00:00",
            "updated_at": "2023-03-22T13:29:41.827456+00:00",
            "published_date": "2022-10-28",
            "notes": "",
            "summary": "The Wuhan Institute of Virology, the cutting-edge ...",
            "image_url": "https://media.vanityfair.com/photos/63599642578d980751943b65/16:9/w_1280,c_limit/vf-1022-covid-trackers-site-story.jpg",
            "parent_id": null,
            "reading_progress": 0,
            "first_opened_at": "2023-03-26T21:02:51.618751+00:00",
            "last_opened_at": "2023-03-26T21:02:51.618751+00:00",
            "saved_at": "2023-03-26T21:02:51.618751+00:00",
            "last_moved_at": "2023-03-27T21:03:52.118752+00:00",
        }
    ]
}
```

--------------------------------

### GET /api/v3/tags/

Source: https://readwise.io/reader_api

Retrieves a list of tags associated with the user's documents.

```APIDOC
## GET /api/v3/tags/

### Description
Retrieves a paginated list of tags.

### Method
GET

### Endpoint
https://readwise.io/api/v3/tags/

### Parameters
#### Query Parameters
- **pageCursor** (string) - Optional - A string returned by a previous request to get the next page of tags.

### Response
#### Success Response (200)
- **count** (integer) - Total number of tags.
- **nextPageCursor** (string) - Cursor for the next page of results.
- **results** (array) - List of tag objects containing key and name.
```

--------------------------------

### Bulk Update Response Structure

Source: https://readwise.io/reader_api

Example of the JSON response body returned by the API, indicating the success or failure status for each document ID.

```json
{
    "results": [
        {"id": "abc123", "success": true},
        {"id": "def456", "success": true},
        {"id": "ghi789", "success": false, "error": "Document not found"}
    ]
}
```

--------------------------------

### GET /api/v3/list/

Source: https://readwise.io/reader_api

Retrieves a list of documents for the authenticated user. Supports pagination via pageCursor and filtering by location or update timestamp.

```APIDOC
## GET /api/v3/list/

### Description
Retrieves a paginated list of documents from the user's Readwise Reader account. The endpoint supports filtering by document location and modification date.

### Method
GET

### Endpoint
https://readwise.io/api/v3/list/

### Parameters
#### Query Parameters
- **pageCursor** (string) - Optional - The cursor used for pagination to fetch the next set of results.
- **updatedAfter** (string) - Optional - ISO 8601 formatted timestamp to filter documents updated after this date.
- **location** (string) - Optional - Filter documents by location (e.g., 'archive', 'later').

### Response
#### Success Response (200)
- **results** (array) - A list of document objects.
- **nextPageCursor** (string) - The cursor to use for fetching the next page of results.
```

--------------------------------

### GET https://readwise.io/api/v3/list/

Source: https://readwise.io/reader_api

Retrieves a list of documents, including articles, emails, RSS feeds, highlights, and notes, based on specified query parameters.

```APIDOC
## GET https://readwise.io/api/v3/list/

### Description
Retrieves a list of documents from the Readwise Reader account. This endpoint supports filtering by ID, update date, location, category, and tags, as well as pagination and optional content inclusion.

### Method
GET

### Endpoint
https://readwise.io/api/v3/list/

### Parameters
#### Query Parameters
- **id** (string) - Optional - The document's unique id. Using this parameter it will return just one document, if found.
- **updatedAfter** (string) - Optional - Fetch only documents updated after this date (ISO 8601).
- **location** (string) - Optional - The document's location (new, later, shortlist, archive, feed).
- **category** (string) - Optional - The document's category (article, email, rss, highlight, note, pdf, epub, tweet, video).
- **tag** (string) - Optional - The document's tag key. Pass up to 5 tag parameters to find documents having all the tags listed. Pass empty value to find untagged documents.
- **limit** (integer) - Optional - The maximum number of documents to return, between 1 and 100. Default is 100.
- **pageCursor** (string) - Optional - A string returned by a previous request to this endpoint to get the next page.
- **withHtmlContent** (boolean) - Optional - Include the html_content field in each document's data.
- **withRawSourceUrl** (boolean) - Optional - Include the raw_source_url field in each document's data.

### Response
#### Success Response (200)
- **documents** (array) - A list of document objects. Highlights and notes are included as documents with a parent_id.
```

--------------------------------

### Fetch Document List via cURL

Source: https://readwise.io/reader_api

Directly query the API using cURL with authorization headers.

```bash
$ curl -v https://readwise.io/api/v3/list/?location=later -H "Authorization: Token XXX" -H "Content-Type: application/json"
```

--------------------------------

### Fetch Document List in Python

Source: https://readwise.io/reader_api

Uses the requests library to fetch documents, requiring an access token and handling pagination.

```python
import datetime
import requests  # This may need to be installed from pip

token = 'XXX'

def fetch_reader_document_list_api(updated_after=None, location=None):
    full_data = []
    next_page_cursor = None
    while True:
        params = {}
        if next_page_cursor:
            params['pageCursor'] = next_page_cursor
        if updated_after:
            params['updatedAfter'] = updated_after
        if location:
            params['location'] = location
        print("Making export api request with params " + str(params) + "...")
        response = requests.get(
            url="https://readwise.io/api/v3/list/",
            params=params,
            headers={"Authorization": f"Token {token}"}, verify=False
        )
        full_data.extend(response.json()['results'])
        next_page_cursor = response.json().get('nextPageCursor')
        if not next_page_cursor:
            break
    return full_data

# Get all of a user's documents from all time
all_data = fetch_reader_document_list_api()

# Get all of a user's archived documents
archived_data = fetch_reader_document_list_api(location='archive')

# Later, if you want to get new documents updated after some date, do this:
docs_after_date = datetime.datetime.now() - datetime.timedelta(days=1)  # use your own stored date
new_data = fetch_reader_document_list_api(docs_after_date.isoformat())
```

--------------------------------

### Handle Document Creation Response

Source: https://readwise.io/reader_api

The API returns a 201 status code upon successful creation, or 200 if the document already exists, along with the document ID and URL.

```json
{
    "id": "0000ffff2222eeee3333dddd4444",
    "url": "https://read.readwise.io/new/read/0000ffff2222eeee3333dddd4444",
}
```

--------------------------------

### Fetch Document List in JavaScript

Source: https://readwise.io/reader_api

Uses the Fetch API to retrieve documents, handling pagination via a cursor loop.

```javascript
const token = "XXX"; // use your access token here

const fetchDocumentListApi = async (updatedAfter=null, location=null) => {
    let fullData = [];
    let nextPageCursor = null;

    while (true) {
      const queryParams = new URLSearchParams();
      if (nextPageCursor) {
        queryParams.append('pageCursor', nextPageCursor);
      }
      if (updatedAfter) {
        queryParams.append('updatedAfter', updatedAfter);
      }
      if (location) {
        queryParams.append('location', location);
      }
      console.log('Making export api request with params ' + queryParams.toString());
      const response = await fetch('https://readwise.io/api/v3/list/?' + queryParams.toString(), {
        method: 'GET',
        headers: {
          Authorization: `Token ${token}`,
        },
      });
      const responseJson = await response.json();
      fullData.push(...responseJson['results']);
      nextPageCursor = responseJson['nextPageCursor'];
      if (!nextPageCursor) {
        break;
      }
    }
    return fullData;
};

// Get all of a user's documents from all time
const allData = await fetchDocumentListApi();

// Get all of a user's archived documents
const archivedData = await fetchDocumentListApi(null, 'archive');

// Later, if you want to get new documents updated after some date, do this:
const docsAfterDate = new Date(Date.now() - 24 * 60 * 60 * 1000);  // use your own stored date
const newData = await fetchDocumentListApi(docsAfterDate.toISOString());
```

--------------------------------

### List tags

Source: https://readwise.io/reader_api

Retrieves a list of tags associated with documents. Supports pagination via the pageCursor parameter.

```json
{
    "count": 2,
    "nextPageCursor": null,
    "results": [
        {
            "key": "first-tag",
            "name": "First tag"
        },
        {
            "key": "second-tag",
            "name": "Second tag"
        }
    ]
}
```

--------------------------------

### POST https://readwise.io/api/v3/save/

Source: https://readwise.io/reader_api

Saves a new document to the Reader library.

```APIDOC
## POST https://readwise.io/api/v3/save/

### Description
Saves a new document to Reader. If html is not provided, the service will attempt to scrape the URL.

### Method
POST

### Endpoint
https://readwise.io/api/v3/save/

### Request Body
- **url** (string) - Required - The document's unique URL.
- **html** (string) - Optional - The document's content in valid HTML.
- **should_clean_html** (boolean) - Optional - Whether to automatically clean HTML and parse metadata.
- **title** (string) - Optional - Overwrites the document title.
- **author** (string) - Optional - Overwrites the document author.
- **summary** (string) - Optional - Summary of the document.
- **language** (string) - Optional - Language code (e.g., 'en', 'de').
- **published_date** (date) - Optional - ISO 8601 datetime string.
- **image_url** (string) - Optional - URL for the cover image.
- **location** (string) - Optional - Initial location: 'new', 'later', 'archive', or 'feed'.
- **category** (string) - Optional - Document category: 'article', 'email', 'rss', 'highlight', 'note', 'pdf', 'epub', 'tweet', or 'video'.
- **saved_using** (string) - Optional - Source of the document.
- **tags** (list) - Optional - List of strings containing tags.
- **notes** (string) - Optional - Top-level note for the document.

### Response
#### Success Response (201/200)
- **id** (string) - The unique identifier of the document.
- **url** (string) - The URL to access the document in Reader.
```

--------------------------------

### Bulk Update Request Body Structure

Source: https://readwise.io/reader_api

The JSON structure required for the PATCH request body, containing an array of document update objects.

```json
{
    "updates": [
        {"id": "<document_id>", "location": "archive", "seen": true},
        {"id": "<document_id>", "category": "pdf"},
        {"id": "<document_id>", "tags": ["reading-list"]}
    ]
}
```

--------------------------------

### PATCH /api/v3/bulk_update/

Source: https://readwise.io/reader_api

Updates multiple documents in a single request. Fields omitted from an item remain unchanged.

```APIDOC
## PATCH /api/v3/bulk_update/

### Description
Use this API to update multiple documents in a single request. Each item in the updates array can specify different fields to update.

### Method
PATCH

### Endpoint
https://readwise.io/api/v3/bulk_update/

### Parameters
#### Request Body
- **updates** (list) - Required - A list of objects containing document updates. Maximum 50 items per request.

**Per-item fields:**
- **id** (string) - Required - The document ID to update
- **title** (string) - Optional - The document's title
- **author** (string) - Optional - The document's author
- **summary** (string) - Optional - Summary of the document
- **language** (string) - Optional - The document's language code
- **published_date** (date) - Optional - A datetime in ISO 8601 format
- **image_url** (string) - Optional - An image URL to use as cover image
- **seen** (boolean) - Optional - Mark the document as seen/unseen
- **location** (string) - Optional - One of: new, later, archive or feed
- **category** (string) - Optional - One of: article, email, rss, pdf, epub, tweet or video
- **tags** (list) - Optional - A list of tag strings
- **notes** (string) - Optional - A string to replace the current document note

### Request Example
{
    "updates": [
        {"id": "abc123", "location": "archive", "seen": true},
        {"id": "def456", "category": "pdf"}
    ]
}

### Response
#### Success Response (200)
- **results** (list) - List of update statuses for each document ID.

#### Response Example
{
    "results": [
        {"id": "abc123", "success": true},
        {"id": "def456", "success": true}
    ]
}
```

--------------------------------

### Delete a document

Source: https://readwise.io/reader_api

Sends a DELETE request to remove a specific document by its ID. Requires an Authorization header with a valid API token.

```javascript
$.ajax({
  url: 'https://readwise.io/api/v3/delete/0000ffff2222eeee3333dddd4444',
  type: 'DELETE',
  beforeSend: function (xhr) {
    xhr.setRequestHeader('Authorization', 'Token XXX');
    },
  success: function (result) {console.log(result)},
  error: function (error) {console.log(error)},
});
```

```python
import requests
requests.delete(
    url="https://readwise.io/api/v3/delete/0000ffff2222eeee3333dddd4444",
    headers={"Authorization": "Token XXX"},
)
```

```bash
$ curl -v https://readwise.io/api/v3/delete/0000ffff2222eeee3333dddd4444 -H "Authorization: Token XXX" -X DELETE
```

--------------------------------

### DELETE /api/v3/delete/<document_id>/

Source: https://readwise.io/reader_api

Deletes a specific document from the user's account.

```APIDOC
## DELETE /api/v3/delete/<document_id>/

### Description
Deletes a document identified by its ID.

### Method
DELETE

### Endpoint
https://readwise.io/api/v3/delete/<document_id>/

### Parameters
#### Path Parameters
- **document_id** (string) - Required - The unique identifier of the document to delete.

### Response
#### Success Response (204)
- No content returned.
```

--------------------------------

### PATCH https://readwise.io/api/v3/update/<document_id>/

Source: https://readwise.io/reader_api

Updates specific fields of a document. Fields omitted from the request remain unchanged.

```APIDOC
## PATCH https://readwise.io/api/v3/update/<document_id>/

### Description
Updates specific fields of a document. Fields omitted from the request will remain unchanged.

### Method
PATCH

### Endpoint
https://readwise.io/api/v3/update/<document_id>/

### Parameters
#### Path Parameters
- **document_id** (string) - Required - The unique identifier of the document.

#### Request Body
- **title** (string) - Optional - The document's title.
- **author** (string) - Optional - The document's author.
- **summary** (string) - Optional - Summary of the document.
- **language** (string) - Optional - The document's language code.
- **published_date** (date) - Optional - ISO 8601 formatted datetime.
- **image_url** (string) - Optional - An image URL to use as cover image.
- **seen** (boolean) - Optional - Mark the document as seen/unseen.
- **location** (string) - Optional - One of: new, later, archive or feed.
- **category** (string) - Optional - One of: article, email, rss, highlight, note, pdf, epub, tweet or video.
- **tags** (list) - Optional - A list of strings containing tags.
- **notes** (string) - Optional - A string to replace the current Document note.

### Response
#### Success Response (200)
- **id** (string) - The document ID.
- **url** (string) - The URL to the document in Reader.

#### Response Example
{
    "id": "0000ffff2222eeee3333dddd4444",
    "url": "https://read.readwise.io/new/read/0000ffff2222eeee3333dddd4444"
}
```
Tokens:
Raw