Readwise API

https://readwise.io/api_deets
Admin
Readwise API provides REST endpoints for developers to create, fetch, update, and delete highlights...
Tokens:16,742
Snippets:82
Trust Score:9.9
Update:5 months ago
Show doc for...
Tokens:
Raw
### API Response Example

Source: https://readwise.io/api_deets

This is an example of the JSON response received after successfully creating or updating highlights. It includes details about the associated books or articles, such as their IDs, titles, authors, and the IDs of the modified highlights.

```json
[
  {
    "id": 111,
    "title": "Moby Dick",
    "author": "Herman Melville",
    "category": "books",
    "source": "api_book",
    "num_highlights": 2,
    "last_highlight_at": null,
    "updated": "2020-10-08T12:00:22.447912Z",
    "cover_image_url": "https://readwise.io/static/images/default-book-icon-0.png",
    "highlights_url": "https://readwise.io/bookreview/111",
    "source_url": null,
    "asin": null,
    "tags": [],
    "document_note": "",
    "modified_highlights": [
      1337
    ]
  }
]
                  

```

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

### Get Specific Highlight Detail (Python)

Source: https://readwise.io/api_deets

Retrieve the details for a specific highlight by its ID using Python. This example demonstrates making a GET request with the necessary Authorization header.

```python
import requests

response = requests.get(
    url="https://readwise.io/api/v2/highlights/13/",
    headers={"Authorization": "Token XXX"},
)

data = response.json()
```

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

### Get Specific Book Details (Python)

Source: https://readwise.io/api_deets

This Python example retrieves the details of a specific book by its ID. It makes a GET request to the book's unique URL and includes the authorization header.

```python
import requests

response = requests.get(
    url="https://readwise.io/api/v2/books/1776/",
    headers={"Authorization": "Token XXX"},
)

data = response.json()
```

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

### Create Highlights with Bash (curl)

Source: https://readwise.io/api_deets

This Bash example demonstrates creating a highlight using the 'curl' command-line tool. It includes the necessary headers for authorization and content type, along with a JSON payload specifying highlight details.

```bash
$ curl --request POST --url https://readwise.io/api/v2/highlights/ \
  -H 'Authorization: Token XXX' -H 'Content-Type: application/json' \
  --data '{"highlights":[{"text": "Call me Ishmael","title": "Moby Dick","author": "Herman Melville"}]}'

< HTTP/1.1 200 OK
[{"title":"Moby Dick","highlights_url":"https://readwise.io/bookreview/123"}]
        
```

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

### List Highlights with Parameters (Python)

Source: https://readwise.io/api_deets

This Python example shows how to retrieve highlights, filtering by book ID and a specific date range using query parameters. Ensure you include your API token in the headers.

```python
import requests

# getting highlights from a particular book
# made after February 1st, 2020, 21:35:53 UTC
querystring = {
    "book_id": 1337,
    "highlighted_at__gt": "2020-02-01T21:35:53Z",
}

response = requests.get(
    url="https://readwise.io/api/v2/highlights/",
    headers={"Authorization": "Token XXX"},
    params=querystring
)

data = response.json()
```

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

### Update Highlight with Python

Source: https://readwise.io/api_deets

This Python example demonstrates how to send a PATCH request to update a highlight, specifying new values for color and note. The API token is passed in the headers.

```python
import requests

payload = {
    "color": "green",
    "note": "This makes me think of what Marcus Aurelius wrote",
}

response = requests.patch(
    url="https://readwise.io/api/v2/highlights/13/",
    headers={"Authorization": "Token XXX"},
    data=payload
)

data = response.json()
```

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

### Fetch Book Tag Detail with Python

Source: https://readwise.io/api_deets

Use the requests library to get details for a specific book tag. Include your API token in the request headers.

```python
import requests

response = requests.get(
    url="https://readwise.io/api/v2/books/59767830/tags/11311390",
    headers={"Authorization": "Token XXX"},
)

data = response.json()
```

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

### Get Specific Book Details (JavaScript)

Source: https://readwise.io/api_deets

Fetch the details for a single book using its ID. This JavaScript snippet shows how to make a GET request to the book detail endpoint, including authorization.

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

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

### Export Highlights with Readwise API

Source: https://readwise.io/api_deets

This code snippet demonstrates how to fetch highlights from the Readwise API. It handles authentication using a token and paginates through results until all highlights are retrieved. Ensure you have a valid API token and the 'requests' library installed.

```python
import requests

token = "YOUR_API_TOKEN"
params = {}
full_data = []

while True:
    response = requests.get(
        "https://readwise.io/api/v2/highlights/",
        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
    params['nextPageCursor'] = next_page_cursor

print(f"Retrieved {len(full_data)} highlights.")
```

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

### Get Daily Review Highlights

Source: https://readwise.io/api_deets

Retrieves your daily review highlights from Readwise.

```APIDOC
## Daily Review LIST

Returns your daily review highlights

### Method
GET

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

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **review_id** (integer) - The ID of the review.
- **review_url** (string) - The URL to the review.
- **review_completed** (boolean) - Indicates if the review is completed.
- **highlights** (array) - A list of highlight objects.
  - **text** (string) - The content of the highlight.
  - **title** (string) - The title of the book/source.
  - **author** (string) - The author of the book/source.
  - **url** (string) - URL of the highlight (if applicable).
  - **source_url** (string) - URL of the source.
  - **source_type** (string) - Type of the source (e.g., 'book').
  - **category** (string) - Category of the highlight.
  - **location_type** (string) - Type of location (e.g., 'page').
  - **location** (integer) - Location of the highlight (e.g., page number).
  - **note** (string) - User-added note for the highlight.
  - **highlighted_at** (string) - Timestamp when the highlight was made.
  - **highlight_url** (string) - URL to the specific highlight.
  - **image_url** (string) - URL of the associated image.
  - **id** (integer) - The unique ID of the highlight.
  - **api_source** (string) - The API source of the highlight.

### Response Example
```json
{
	"review_id": 877266693,
	"review_url": "https://readwise.io/reviews/877266693",
	"review_completed": false,
	"highlights": [
		{
			"text": "Few of the great creators have bland personalities. They are cantankerous egotists, the kind of men who are unwelcome in  the modern corporation. Consider Winston Churchill. He drank like a fish. He was capricious and wilful. When opposed, he sulked. He was rude to fools. He was wildly extravagant. He wept on the slightest provocation. His conversation was Rabelaisian.\n\nHe was inconsiderate to his staff. Yet Lord Alanbrooke, his Chief of Staff, could write:\n\nI shall always look back on the years I worked with him as some of the most difficult and trying ones in my life. For all that I thank God that I was given the opportunity of working alongside of such a man, and of having my eyes opened to the fact that occasionally such supermen exist on this earth.",
			"title": "Confessions of an Advertising Man",
			"author": "David  Ogilvy",
			"url": null,
			"source_url": null,
			"source_type": "book",
			"category": null,
			"location_type": "page",
			"location": 45,
			"note": "On great creators and Churchill",
			"highlighted_at": "2023-05-31T14:47:36.344000Z",
			"highlight_url": null,
			"image_url": "https://m.media-amazon.com/images/I/51iTic+feKL.jpg",
			"id": 539866941,
			"api_source": null
		}
    ]
}
```
```

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

### Get Book Tag Detail

Source: https://readwise.io/api_deets

Retrieve the details of a specific tag associated with a book using its book ID and tag ID.

```json
{
  "id": 11311390,
  "name": "philosophy"
}
```

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

### Highlight CREATE

Source: https://readwise.io/api_deets

This endpoint allows you to create new highlights in Readwise. You can provide various details for each highlight, such as text, title, author, source URL, source type, category, and an optional note. Minimal examples only require the 'text' field.

```APIDOC
## POST /highlights/

### Description
Create new highlights in Readwise. Supports detailed information for articles and books, or minimal text-only highlights.

### Method
POST

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

### Parameters
#### Request Body
- **highlights** (array) - Required - An array of highlight objects.
  - **text** (string) - Required - The content of the highlight.
  - **title** (string) - Optional - The title of the source (e.g., book or article).
  - **author** (string) - Optional - The author of the source.
  - **source_url** (string) - Optional - The URL of the source.
  - **source_type** (string) - Optional - The type of the source (e.g., 'my_app', 'kindle').
  - **category** (string) - Optional - The category of the source (e.g., 'articles', 'books').
  - **note** (string) - Optional - A personal note attached to the highlight.
  - **location_type** (string) - Optional - The type of location (e.g., 'page', 'chapter').
  - **location** (integer) - Optional - The location number within the source.
  - **highlighted_at** (string) - Optional - The timestamp when the highlight was made (ISO 8601 format).

### Request Example (JavaScript)
```javascript
$.ajax({
  url: 'https://readwise.io/api/v2/highlights/',
  type: 'POST',
  contentType: 'application/json',
  beforeSend: function (xhr) {
    xhr.setRequestHeader('Authorization', 'Token XXX');
    },
  data: JSON.stringify({
  'highlights': [
    {
      'text': 'To be happy I think you have to be doing... ',
      'title': 'How to Do What You Love',
      'author': 'Paul Graham',
      'source_url': 'http://www.paulgraham.com/love.html',
      'source_type': 'my_app',
      'category': 'articles',
      'note': 'Love this quote',
    },
    {
      'text': 'My lovely passage',
    },
  ],
  }),
  success: function (result) {console.log(result)},
  error: function (error) {console.log(error)},
});
```

### Request Example (Python)
```python
import requests
requests.post(
    url="https://readwise.io/api/v2/highlights/",
    headers={"Authorization": "Token XXX"},
    json={
        "highlights": [{
            "text": "Call me Ishmael",
            "title": "Moby Dick",
            "author": "Herman Melville",
            "source_type": "my_reading_app",
            "category": "books",
            "location_type": "page",
            "location": 3,
            "highlighted_at": "2020-07-14T20:11:24+00:00",
        }]
    }
)
```

### Request Example (Bash)
```bash
curl --request POST --url https://readwise.io/api/v2/highlights/ \
  -H 'Authorization: Token XXX' -H 'Content-Type: application/json' \
  --data '{"highlights":[{"text": "Call me Ishmael","title": "Moby Dick","author": "Herman Melville"}]}'
```

### Response
#### Success Response (200)
- **title** (string) - The title of the book or source.
- **highlights_url** (string) - A URL to view the highlights for the given source.
```

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

### Get Highlight Tag

Source: https://readwise.io/api_deets

Retrieves a specific tag associated with a highlight.

```APIDOC
## Highlight Tag DETAIL

### Description
Retrieves a specific tag associated with a highlight.

### Method
GET

### Endpoint
https://readwise.io/api/v2/highlights/<highlight id>/tags/<tag id>

### Parameters
This endpoint doesn't take any parameters.

### Response
#### Success Response (200)
- **id** (integer) - The tag's ID.
- **name** (string) - The tag's name.

### Response Example
```json
{
  "id": 11311390,
  "name": "philosophy"
}
```
```

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

### Get Highlight Tag Detail

Source: https://readwise.io/api_deets

Retrieve details for a specific tag associated with a highlight. Requires the highlight ID and tag ID.

```JavaScript
$.ajax({
  url: 'https://readwise.io/api/v2/highlights/59767830/tags/11311390',
  type: 'GET',
  contentType: 'application/json',
  beforeSend: function (xhr) {
    xhr.setRequestHeader('Authorization', 'Token XXX');
  },
  success: function (result) {
    console.log(result)
  },
  error: function (error) {
    console.log(error)
  },
});
```

```Python
import requests

response = requests.get(
    url="https://readwise.io/api/v2/highlights/59767830/tags/11311390",
    headers={"Authorization": "Token XXX"},
)

data = response.json()
```

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

### Get Specific Highlight Detail (JavaScript)

Source: https://readwise.io/api_deets

Fetch the details of a single highlight using its ID. This JavaScript snippet includes setting the Authorization header.

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

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

### Authentication Check

Source: https://readwise.io/api_deets

Verify your Readwise API token by making a GET request to the authentication endpoint. A successful request returns a 204 No Content status.

```APIDOC
## GET /api/v2/auth/

### Description
Checks if the provided API token is valid.

### Method
GET

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

### Headers
- **Authorization** (string) - Required - `Token YOUR_ACCESS_TOKEN`

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

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

### Create Highlights with Python (requests)

Source: https://readwise.io/api_deets

This Python snippet uses the 'requests' library to send a POST request to create a highlight. It shows how to include essential highlight details like text, title, author, and source type in the JSON payload.

```python
import requests
requests.post(
    url="https://readwise.io/api/v2/highlights/",
    headers={"Authorization": "Token XXX"},
    json={
        "highlights": [{
            "text": "Call me Ishmael",
            "title": "Moby Dick",
            "author": "Herman Melville",
            "source_type": "my_reading_app",
            "category": "books",
            "location_type": "page",
            "location": 3,
            "highlighted_at": "2020-07-14T20:11:24+00:00",
        }]
    }
)
        
```

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

### Create Highlight Tag

Source: https://readwise.io/api_deets

Creates a new tag for a highlight.

```APIDOC
## Highlight Tag CREATE

### Description
Creates a new tag for a highlight.

### Method
POST

### Endpoint
https://readwise.io/api/v2/highlights/<highlight id>/tags/

### Parameters
#### Request Body
- **name** (string) - Required - The tag's name. Maximum length: 127 characters.

### Response
#### Success Response (200)
- **id** (integer) - The tag's ID.
- **name** (string) - The tag's name.

### Response Example
```json
{
  "id": 11311390,
  "name": "philosophy"
}
```
```

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

### List Highlight Tags with Python

Source: https://readwise.io/api_deets

This Python script fetches tags for a given highlight via the Readwise API. It includes pagination parameters and requires an Authorization token.

```python
import requests

response = requests.get(
    url="https://readwise.io/api/v2/highlights/59767830/tags",
    headers={"Authorization": "Token XXX"},
)

data = response.json()
```

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

### List Highlights with Parameters (JavaScript)

Source: https://readwise.io/api_deets

Use this snippet to fetch a list of highlights from the Readwise API. It demonstrates how to set the Authorization header and pass query parameters like page_size.

```javascript
$.ajax({
  url: 'https://readwise.io/api/v2/highlights/',
  type: 'GET',
  contentType: 'application/json',
  beforeSend: function (xhr) {
    xhr.setRequestHeader('Authorization', 'Token XXX');
  },
  data: {"page_size": 10},
  success: function (result) {
    console.log(result)
  },
  error: function (error) {
    console.log(error)
  },
});
```

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

### Fetch Daily Review Highlights (Python)

Source: https://readwise.io/api_deets

This Python function retrieves your daily review highlights using the requests library. Replace 'XXX' with your access token. Note that `verify=False` is used, which may have security implications.

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

token = 'XXX'

def fetch_daily_review():
    response = requests.get(
        url="https://readwise.io/api/v2/review/",
        headers={"Authorization": f"Token {token}"}, verify=False
    )
    return response.json()

daily_review_highlights = fetch_daily_review()
```

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

### Fetch Book Tags with Python

Source: https://readwise.io/api_deets

Use the requests library to fetch tags for a specific book. The API token should be provided in the headers.

```python
import requests

response = requests.get(
    url="https://readwise.io/api/v2/books/59767830/tags",
    headers={"Authorization": "Token XXX"},
)

data = response.json()
```

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

### Fetch All Highlights with Pagination (Python)

Source: https://readwise.io/api_deets

This Python function demonstrates how to fetch all highlights from the Readwise API, handling pagination by repeatedly calling the export endpoint until all pages are retrieved. It supports fetching highlights updated after a specific date.

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

token = 'XXX'

def fetch_from_export_api(updated_after=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
        print("Making export api request with params " + str(params) + "...")
        response = requests.get(
            url="https://readwise.io/api/v2/export/",

```

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

### Highlight CREATE

Source: https://readwise.io/api_deets

Saves highlights to a user's Readwise account. This endpoint can also be used to update existing highlights if a `highlight_url` is provided.

```APIDOC
## Highlight CREATE

### Description
If you want to save highlights to a user's Readwise account from your own application, this is the only endpoint you should need.

### Method
`POST`

### Endpoint
`https://readwise.io/api/v2/highlights/`

### Parameters
#### Request Body
A JSON object with the key `highlights`, pointing to an array of objects, each with these keys:

- **text** (string) - Required - The highlight text. Maximum length: 8191 characters.
- **title** (string) - Optional - Title of the book/article/podcast. Maximum length: 511 characters.
- **author** (string) - Optional - Author of the book/article/podcast. Maximum length: 1024 characters.
- **image_url** (string) - Optional - The url of a cover image for this book/article/podcast. Maximum length: 2047 characters.
- **source_url** (string) - Optional - The url of the article/podcast. Maximum length: 2047 characters.
- **source_type** (string) - Optional - A meaningful unique identifier for your app (string between 3 and 64 chars, no spaces). Example: `my_app`.
- **category** (string) - Optional - One of: `books`, `articles`, `tweets` or `podcasts`. Defaults to `articles` if `source_url` is provided, otherwise `books`.
- **note** (string) - Optional - Annotation note attached to the specific highlight. Maximum length: 8191 characters.
- **location** (integer) - Optional - Highlight's location in the source text. Used to order the highlights. If not provided, order is based on the list. If `location_type` is `time_offset`, this is interpreted as seconds from the start.
- **location_type** (string) - Optional - One of: `page`, `location`, `none`, `order`, `offset` or `time_offset`. Defaults to `order`.
- **highlighted_at** (string) - Optional - A datetime representing when the highlight was taken in ISO 8601 format (e.g., `"2020-07-14T20:11:24+00:00"`). Default timezone is UTC.
- **highlight_url** (string) - Optional - Unique url of the specific highlight. Maximum length: 4095 characters.

### Request Example
```json
{
  "highlights": [
    {
      "text": "Call me Ishmael",
      "title": "Moby Dick",
      "author": "Herman Melville"
    },
    {
      "text": "...but don't ever call me an octopus",
      "title": "Moby Dick",
      "author": "Herman Melville"
    }
  ]
}
```

### Response
#### Success Response (200)
Returns a list of created/updated books/articles/podcasts.

- **id** (integer) - Unique identifier for the book/article/podcast.
- **title** (string) - Title of the book/article/podcast.
- **author** (string) - Author of the book/article/podcast.
- **category** (string) - Category of the item (e.g., `books`, `articles`).
- **source** (string) - Source identifier.
- **num_highlights** (integer) - Number of highlights associated with this item.
- **last_highlight_at** (string) - Timestamp of the last highlight.
- **updated** (string) - Timestamp of the last update.
- **cover_image_url** (string) - URL of the cover image.
- **highlights_url** (string) - URL to view the highlights for this item.
- **source_url** (string) - URL of the source.
- **asin** (string) - ASIN for books.
- **tags** (array) - List of tags associated with the item.
- **document_note** (string) - Note for the document.
- **modified_highlights** (array) - List of IDs of highlights that were created or updated.

#### Response Example
```json
[
  {
    "id": 111,
    "title": "Moby Dick",
    "author": "Herman Melville",
    "category": "books",
    "source": "api_book",
    "num_highlights": 2,
    "last_highlight_at": null,
    "updated": "2020-10-08T12:00:22.447912Z",
    "cover_image_url": "https://readwise.io/static/images/default-book-icon-0.png",
    "highlights_url": "https://readwise.io/bookreview/111",
    "source_url": null,
    "asin": null,
    "tags": [],
    "document_note": "",
    "modified_highlights": [
      1337
    ]
  }
]
```
```

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

### List Books with Filters (JavaScript)

Source: https://readwise.io/api_deets

Use this snippet to fetch a list of books from your Readwise account. It demonstrates how to set query parameters like page size and category, and includes authorization headers.

```javascript
$.ajax({
  url: 'https://readwise.io/api/v2/books/',
  type: 'GET',
  contentType: 'application/json',
  beforeSend: function (xhr) {
    xhr.setRequestHeader('Authorization', 'Token XXX');
  },
  data: {"page_size": 500, "category": "articles"},
  success: function (result) {
    console.log(result)
  },
  error: function (error) {
    console.log(error)
  },
});
```

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

### Create Book Tag

Source: https://readwise.io/api_deets

Creates a new tag for a specific book.

```APIDOC
## Book Tag CREATE

### Description
Creates a new tag for a specific book.

### Method
POST

### Endpoint
https://readwise.io/api/v2/books/<book id>/tags/

### Request Body
- **name** (string) - Required - The tag's name. Maximum length: 512 characters.

### Request Example
```json
{
  "name": "philosophy"
}
```

### Success Response (200)
- **id** (integer) - The unique identifier for the tag.
- **name** (string) - The name of the tag.

### Response Example
```json
{
  "id": 11311390,
  "name": "philosophy"
}
```
```

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

### Fetch Book Tags with JavaScript

Source: https://readwise.io/api_deets

Use jQuery's AJAX to fetch tags for a specific book. Ensure to include your API token in the Authorization header.

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

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

### Create Highlight Tag

Source: https://readwise.io/api_deets

Create a new tag for a highlight. The tag name must be a string with a maximum length of 127 characters. Requires the highlight ID.

```JavaScript
$.ajax({
  url: 'https://readwise.io/api/v2/highlights/59767830/tags',
  type: 'POST',
  contentType: 'application/json',
  beforeSend: function (xhr) {
    xhr.setRequestHeader('Authorization', 'Token XXX');
  },
  data: JSON.stringify({
    "name": "philosophy",
  }),
  success: function (result) {
    console.log(result)
  },
  error: function (error) {
    console.log(error)
  },
});
```

```Python
import requests

requests.post(
    url="https://readwise.io/api/v2/highlights/59767830/tags",
    headers={"Authorization": "Token XXX"},
    json={"name": "philosophy"}
)

data = response.json()
```

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

### Create Highlights with JavaScript (jQuery AJAX)

Source: https://readwise.io/api_deets

Use this snippet to create highlights from your web application using jQuery's AJAX method. It demonstrates sending a POST request with a JSON payload containing multiple highlights, including detailed metadata and notes.

```javascript
$.ajax({
  url: 'https://readwise.io/api/v2/highlights/',
  type: 'POST',
  contentType: 'application/json',
  beforeSend: function (xhr) {
    xhr.setRequestHeader('Authorization', 'Token XXX');
    },
  data: JSON.stringify({
  'highlights': [
    {
      // A highlight from an article,
      // with an attached note the user made.
      'text': 'To be happy I think you have to be doing... ',
      'title': 'How to Do What You Love',
      'author': 'Paul Graham',
      'source_url': 'http://www.paulgraham.com/love.html',
      'source_type': 'my_app',
      'category': 'articles',
      'note': 'Love this quote',
    },
    {
      // Minimal example: just a text highlight.
      // By default, this will be put into a generic "Quotes" book.
      'text': 'My lovely passage',
    },
  ],
  }),
  success: function (result) {console.log(result)},
  error: function (error) {console.log(error)},
});
        
```

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

### Create Book Tag with Python

Source: https://readwise.io/api_deets

Use the requests library to create a new book tag. The tag name is sent as a JSON object in the request.

```python
import requests

requests.post(
    url="https://readwise.io/api/v2/books/59767830/tags",
    headers={"Authorization": "Token XXX"},
    json={"name": "philosophy"}
)

data = response.json()
```

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

### Fetch All Highlights with Pagination (JavaScript)

Source: https://readwise.io/api_deets

This JavaScript function demonstrates how to fetch all highlights from the Readwise API, handling pagination by repeatedly calling the export endpoint until all pages are retrieved. It supports fetching highlights updated after a specific date.

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

const fetchFromExportApi = async (updatedAfter=null) => {
    let fullData = [];
    let nextPageCursor = null;

    while (true) {
      const queryParams = new URLSearchParams();
      if (nextPageCursor) {
        queryParams.append('pageCursor', nextPageCursor);
      }
      if (updatedAfter) {
        queryParams.append('updatedAfter', updatedAfter);
      }
      console.log('Making export api request with params ' + queryParams.toString());
      const response = await fetch('https://readwise.io/api/v2/export/?' + 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 books/highlights from all time
const allData = await fetchFromExportApi();

// Later, if you want to get new highlights updated since your last fetch of allData, do this.
const lastFetchWasAt = new Date(Date.now() - 24 * 60 * 60 * 1000);  // use your own stored date
const newData = await fetchFromExportApi(lastFetchWasAt.toISOString());
          
```

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

### Fetch All Data from Readwise Export API

Source: https://readwise.io/api_deets

Use this function to retrieve all your books and highlights from Readwise. For incremental updates, call the API with a timestamp of your last fetch.

```python
all_data = fetch_from_export_api()

# Later, if you want to get new highlights updated since your last fetch of allData, do this.
last_fetch_was_at = datetime.datetime.now() - datetime.timedelta(days=1)  # use your own stored date
new_data = fetch_from_export_api(last_fetch_was_at.isoformat())
```

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

### List Books Updated Last Week (Python)

Source: https://readwise.io/api_deets

This Python script retrieves books updated within the last week. It constructs a query string with a dynamic date filter and includes the necessary authorization token.

```python
import datetime
import requests

# getting books that were updated last week

a_week_ago = datetime.datetime.now() - datetime.timedelta(days=7)

querystring = {
    "category": "books",
    "updated__gt": a_week_ago.strftime("%Y-%m-%dT%H:%M:%SZ"),
}

response = requests.get(
    url="https://readwise.io/api/v2/books/",
    headers={"Authorization": "Token XXX"},
    params=querystring
)

data = response.json()
```

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

### Highlight EXPORT

Source: https://readwise.io/api_deets

This endpoint allows you to pull all highlights from a user's account. It's useful for integrating with notetaking apps or creating backups.

```APIDOC
## Highlight EXPORT

If you want to pull all of the highlights from a user's account into your service (eg notetaking apps, backups, etc) this endpoint is all you need!

### Method
GET

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

### Parameters
#### Query Parameters
- **updatedAfter** (Optional, Formatted as ISO 8601 date) - Fetch only highlights updated after this date.
- **ids** (Optional) - Comma-separated list of `user_book_id`s, returns all highlights for these books only.
- **includeDeleted** (Optional) - If set to `true`, returns all highlights, including deleted. Use it to synchronize deletions to your app.
- **pageCursor** (Optional) - A string returned by a previous request to this endpoint. Use it to get the next page of books/highlights if there are too many for one request.

### Response
#### Success Response (200)
- **count** (integer) - The number of results returned in this request.
- **nextPageCursor** (string) - A cursor for fetching the next page of results. Null if there are no more pages.
- **results** (array) - An array of highlight objects.
  - **user_book_id** (integer) - The ID of the book associated with the highlight.
  - **is_deleted** (boolean) - Whether the highlight has been deleted.
  - **title** (string) - The title of the book.
  - **author** (string) - The author of the book.
  - **readable_title** (string) - A title suitable for display.
  - **source** (string) - The source of the highlight (e.g., 'raindrop', 'reader').
  - **cover_image_url** (string) - URL for the book's cover image.
  - **unique_url** (string) - A unique URL for the book.
  - **book_tags** (array) - Tags associated with the book.
  - **category** (string) - The category of the book (e.g., 'articles').
  - **document_note** (string) - A note associated with the document.
  - **summary** (string) - A summary of the book.
  - **readwise_url** (string) - The Readwise URL for the book.
  - **external_id** (string) - An external ID for the book, often from the source system.
  - **asin** (string) - The Amazon ASIN for the book, if applicable.
  - **highlights** (array) - An array of highlight objects within this book.
    - **id** (integer) - The ID of the highlight.
    - **is_deleted** (boolean) - Whether the highlight has been deleted.
    - **text** (string) - The content of the highlight.
    - **location** (integer) - The location of the highlight within the source document.
    - **location_type** (string) - The type of location (e.g., 'order').
    - **note** (string) - A personal note added to the highlight.
    - **color** (string) - The color of the highlight.
    - **highlighted_at** (string) - The date and time the highlight was made (ISO 8601 format).
    - **created_at** (string) - The date and time the highlight was created in Readwise (ISO 8601 format).
    - **updated_at** (string) - The date and time the highlight was last updated in Readwise (ISO 8601 format).
    - **external_id** (string) - An external ID for the highlight, often from the source system.
    - **end_location** (integer) - The end location of the highlight, if applicable.
    - **url** (string) - A URL associated with the highlight, if applicable.
    - **book_id** (integer) - The ID of the book this highlight belongs to.
    - **tags** (array) - Tags associated with the highlight.
    - **is_favorite** (boolean) - Whether the highlight is marked as a favorite.
    - **is_discard** (boolean) - Whether the highlight is marked for discard.
    - **readwise_url** (string) - The Readwise URL for the highlight.

### Usage Notes
The recommended way to use this endpoint is to first sync all of a user's historical data by passing no parameters on the first request, then use `pageCursor` until there are no pages left. Later, to pull newly updated highlights, pass `updatedAfter` as the time you last pulled data. All dates used/returned are in UTC.
The `external_id` field serves as a reference to the User Book in the source system it was imported from. This field is currently available only when `source` is `reader`.
```

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

### Highlights LIST

Source: https://readwise.io/api_deets

Retrieves a list of highlights with pagination. Supports filtering by book ID and update times.

```APIDOC
## Highlights LIST

### Description
Retrieves a list of highlights with pagination. Supports filtering by book ID and update times.

### Method
GET

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

### Parameters
#### Query Parameters
- **page_size** (integer) - Optional - Specify number of results per page (default is 100, max is 1000)
- **page** (integer) - Optional - Specify the pagination counter
- **book_id** (integer) - Optional - Return highlights of a specified book
- **updated__lt** (datetime) - Optional - Filter by last updated datetime (less than)
- **updated__gt** (datetime) - Optional - Filter by last updated datetime (greater than)
- **highlighted_at__lt** (datetime) - Optional - Filter by the time when highlight was taken
- **highlighted_at__gt** (datetime) - Optional - Filter by the time when highlight was taken

### Response
#### Success Response (200)
- **count** (integer) - Total number of highlights.
- **next** (string) - URL for the next page of results.
- **previous** (string) - URL for the previous page of results.
- **results** (array) - A list of highlight objects.
  - **id** (integer) - Unique identifier for the highlight.
  - **text** (string) - The content of the highlight.
  - **note** (string) - User-added note for the highlight.
  - **location** (integer) - Location of the highlight within the source.
  - **location_type** (string) - Type of the location (e.g., 'order', 'location').
  - **highlighted_at** (datetime) - Timestamp when the highlight was made.
  - **created_at** (datetime) - Timestamp when the highlight was created in Readwise.
  - **url** (string) - URL associated with the highlight, if any.
  - **color** (string) - Color of the highlight.
  - **updated** (datetime) - Timestamp when the highlight was last updated.
  - **book_id** (integer) - ID of the book the highlight belongs to.
  - **external_id** (string) - External ID of the highlight.
  - **tags** (array) - List of tags associated with the highlight.
    - **id** (integer) - Tag ID.
    - **name** (string) - Tag name.
  - **end_location** (integer) - End location of the highlight, if applicable.
  - **readwise_url** (string) - Direct URL to the highlight in Readwise.

### Request Example
```json
{
  "page_size": 10
}
```

### Response Example
```json
{
  "count": 1163,
  "next": "https://readwise.io/api/v2/highlights?page=2",
  "previous": null,
  "results": [
    {
      "id": 59758950,
      "text": "The fundamental belief of metaphysicians is THE BELIEF IN ANTITHESES OF VALUES.",
      "note": "",
      "location": 9,
      "location_type": "order",
      "highlighted_at": null,
      "created_at": "2020-10-01T12:58:44.716235Z",
      "url": null,
      "color": "",
      "updated": "2020-04-06T12:30:52.318552Z",
      "book_id": 2608248,
      "external_id": null,
      "tags": [
        {
           "id": 123456,
           "name": "philosophy"
        }
      ],
      "end_location": null,
      "readwise_url": "https://readwise.io/open/59758950"
    }
  ]
}
```
```

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

### List Book Tags

Source: https://readwise.io/api_deets

Retrieve a paginated list of tags associated with a specific book. Supports query parameters for pagination.

```json
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": 11311390,
      "name": "philosophy"
    }
  ]
}
```

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

### Highlight DETAIL

Source: https://readwise.io/api_deets

Retrieves the details of a specific highlight by its ID.

```APIDOC
## Highlight DETAIL

### Description
Retrieves the details of a specific highlight by its ID.

### Method
GET

### Endpoint
https://readwise.io/api/v2/highlights/<highlight_id>/

### Parameters
This endpoint doesn't take any parameters.

### Response
#### Success Response (200)
- **id** (integer) - Unique identifier for the highlight.
- **text** (string) - The content of the highlight.
- **note** (string) - User-added note for the highlight.
- **location** (integer) - Location of the highlight within the source.
- **location_type** (string) - Type of the location (e.g., 'order', 'location').
- **highlighted_at** (datetime) - Timestamp when the highlight was made.
- **created_at** (datetime) - Timestamp when the highlight was created in Readwise.
- **url** (string) - URL associated with the highlight, if any.
- **color** (string) - Color of the highlight.
- **updated** (datetime) - Timestamp when the highlight was last updated.
- **book_id** (integer) - ID of the book the highlight belongs to.
- **external_id** (string) - External ID of the highlight.
- **tags** (array) - List of tags associated with the highlight.
  - **id** (integer) - Tag ID.
  - **name** (string) - Tag name.
- **end_location** (integer) - End location of the highlight, if applicable.
- **readwise_url** (string) - Direct URL to the highlight in Readwise.

### Response Example
```json
{
  "id": 13,
  "text": "To be alone for any length of time is to shed an outer skin. The...",
  "note": "",
  "location": 57,
  "location_type": "location",
  "highlighted_at": "2020-02-02T16:46:07Z",
  "created_at": "2020-02-02T16:46:07Z",
  "url": null,
  "color": "yellow",
  "updated": "2020-04-06T12:30:52.318552Z",
  "book_id": 1337,
  "external_id": null,
  "tags": [],
  "end_location": null,
  "readwise_url": "https://readwise.io/open/13"
}
```
```

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

### Fetch Daily Review Highlights (JavaScript)

Source: https://readwise.io/api_deets

This JavaScript function fetches your daily review highlights from the Readwise API. Ensure you replace 'XXX' with your actual access token. The response includes review details and a list of highlights.

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

const fetchDailyReview = async () => {
    let fullData = [];
    let nextPageCursor = null;

    const response = await fetch('https://readwise.io/api/v2/review/', {
        method: 'GET',
        headers: {
          Authorization: `Token ${token}`,
        },
    });
    const responseJson = await response.json();
    return responseJson;
};

const dailyReviewHighlights = await fetchDailyReview();
```

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

### Create Highlights via API

Source: https://readwise.io/api_deets

Use this JavaScript snippet to send highlight data to the Readwise API. Ensure you include an 'Authorization' header with your API token. The 'highlights' array can contain multiple highlight objects, each with optional fields like title, author, and more.

```javascript
$.ajax({
  url: 'https://readwise.io/api/v2/highlights/',
  type: 'POST',
  contentType: 'application/json',
  beforeSend: function (xhr) {
    xhr.setRequestHeader('Authorization', 'Token XXX');
    },
  data: JSON.stringify({
  'highlights': [
    {
      // A highlight in a book
      'text': 'Call me Ishmael',
      'title': 'Moby Dick',
      'author': 'Herman Melville',
    },
    {
      // Another highlight, later in the same book
      'text': "...but don't ever call me an octopus",
      'title': 'Moby Dick',
      'author': 'Herman Melville',
    },
  ],
  }),
  success: function (result) {console.log(result)},
  error: function (error) {console.log(error)},
});
          
```
Tokens:
Raw