### Bulk Update Implementation

Source: https://readwise.io/reader_api

Examples for performing 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"
```

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

### Fetch Tags via API

Source: https://readwise.io/reader_api

Examples for retrieving tags using JavaScript, Python, and Bash. Replace 'XXX' with your actual access token.

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

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

### Fetch Document List with Python

Source: https://readwise.io/reader_api

Uses the requests library to handle paginated API calls. Ensure the requests library is installed via pip.

```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())
```

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

### Document Delete Implementation

Source: https://readwise.io/reader_api

Examples for deleting a document by ID using JavaScript, Python, and Bash.

```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
```

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

### Save Document via Readwise API (Python)

Source: https://readwise.io/reader_api

This Python example demonstrates saving a document using the requests library. It shows how to include the authorization token and specify tags. If HTML is not provided, the URL will be scraped.

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

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

### Save Document via Readwise API (Bash)

Source: https://readwise.io/reader_api

A Bash command using curl to save a document. This example sends a POST request with the URL and sets the necessary Authorization and Content-Type headers.

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

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

### GET /api/v3/list/

Source: https://readwise.io/reader_api

Retrieves a list of documents from the user's Readwise Reader account. Supports pagination via pageCursor and filtering by location or update timestamp.

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

### Description
Retrieves a paginated list of documents saved in the user's Readwise Reader account.

### Method
GET

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

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

### Response
#### Success Response (200)
- **results** (array) - List of document objects.
- **nextPageCursor** (string) - Cursor for the next page of results.

#### Response Example
{
  "results": [
    {
      "id": "01gkqt8nbms4t698abcdvcswvf",
      "url": "https://readwise.io/new/read/01gkqt8nbms4t698abcdvcswvf",
      "title": "COVID-19 Origins: Investigating a “Complex and Grave Situation” Inside a Wuhan Lab",
      "author": "Condé Nast",
      "category": "article",
      "location": "new"
    }
  ],
  "nextPageCursor": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}
```

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

### Authentication

Source: https://readwise.io/reader_api

To authenticate your requests, include an 'Authorization' header with the value 'Token XXX', where XXX is your Readwise access token. You can obtain your token from readwise.io/access_token. A GET request to /api/v2/auth/ with this header will return a 204 status code if the token is valid.

```APIDOC
## 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.
```

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

### Authenticate with Readwise API

Source: https://readwise.io/reader_api

To authenticate, set the 'Authorization' header with your Readwise access token. A GET request to /api/v2/auth/ with this header should return a 204 status code.

```http
GET https://readwise.io/api/v2/auth/
Header: Authorization: Token XXX
```

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

### Update Document Fields (Bash)

Source: https://readwise.io/reader_api

A Bash command using curl to update a document's title. This example shows how to set the Authorization header, HTTP method, and JSON payload.

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

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

### List Documents with Query Parameters

Source: https://readwise.io/reader_api

Demonstrates how to fetch documents using various query parameters to filter results. Supports filtering by ID, update time, location, category, tags, and pagination.

```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",
            "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",
            "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"
        }
    ]
}
```

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

### Webhooks

Source: https://readwise.io/reader_api

Information on setting up webhooks for real-time notifications.

```APIDOC
## Webhooks

Receive real-time notifications about your highlights and documents via webhooks. Configure webhooks to automatically receive updates when highlights are created, updated, or deleted.

For detailed documentation on setting up and using webhooks, including available event types, payload formats, and best practices, please visit:
[Webhooks Documentation](https://readwise.io/api/documentation/webhooks)

You can also configure your webhooks directly in your account settings: [Configure Webhooks](https://readwise.io/settings#webhooks)
```

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

### Fetch Document List with cURL

Source: https://readwise.io/reader_api

A simple command-line request to retrieve documents from the 'later' location.

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

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

### Fetch Document List with JavaScript

Source: https://readwise.io/reader_api

Uses the fetch API to retrieve paginated document lists from Readwise. Requires an authorization token.

```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());
```

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

### Rate Limiting

Source: https://readwise.io/reader_api

Information on API rate limits and how to handle them.

```APIDOC
## Rate Limiting

Requests are rate-limited per access token. Each endpoint's specific rate limit is documented in its section above. When you exceed the limit, a `429 Too Many Requests` response is returned — check the `Retry-After` header for the number of seconds to wait.
```

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

### Save Document via Readwise API (JavaScript)

Source: https://readwise.io/reader_api

Use this JavaScript snippet to save a document by providing its URL and optionally HTML content and tags. Ensure the 'Authorization' header is correctly set.

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

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

### Bulk Update Response Format

Source: https://readwise.io/reader_api

The JSON structure returned by the bulk update endpoint, indicating success or failure for each item.

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

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

### POST /api/v3/save/

Source: https://readwise.io/reader_api

Saves a new document to your Readwise Reader library. You can provide either a URL or HTML content. The API supports various optional parameters for metadata, categorization, and organization.

```APIDOC
## POST /api/v3/save/

### Description
Saves a new document to your Readwise Reader library. You can provide either a URL or HTML content. The API supports various optional parameters for metadata, categorization, and organization.

### Method
POST

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

### Parameters
#### Request Body
- **url** (string) - Required - The document's unique URL. If you don't have one, you can provide a made up value such as `https://yourapp.com#document1`
- **html** (string) - Optional - The document's content, in valid html. If not provided, the URL will be scraped.
- **should_clean_html** (boolean) - Optional - Only valid when `html` is provided. Set to `true` to automatically clean HTML and parse metadata. Defaults to `false`.
- **title** (string) - Optional - Overwrites the document's title.
- **author** (string) - Optional - Overwrites the document's author.
- **summary** (string) - Optional - Summary of the document.
- **published_date** (date) - Optional - Publication date in ISO 8601 format (e.g., `"2020-07-14T20:11:24+00:00"`).
- **image_url** (string) - Optional - URL for the cover image.
- **location** (string) - Optional - Initial location: `new`, `later`, `archive`, or `feed`. Defaults to `new`.
- **category** (string) - Optional - Document category: `article`, `email`, `rss`, `highlight`, `note`, `pdf`, `epub`, `tweet`, or `video`. Defaults to guessed based on URL.
- **saved_using** (string) - Optional - Source of the document.
- **tags** (list) - Optional - A list of strings containing tags (e.g., `["tag1", "tag2"]`).
- **notes** (string) - Optional - A top-level note for the document.

### Request Example
```json
{
  "url": "https://example.com/article/",
  "html": "<div><h1>This article is awesome</h1><p>content here!</p></div>",
  "tags": ["tag1", "tag2"]
}
```

### Response
#### Success Response (200 or 201)
- **id** (string) - The unique identifier of the created document.
- **url** (string) - The URL to access the saved document within Readwise.

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

### Rate Limit
`50/minute` per access token.
```

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

### Retrieve Tags Response Structure

Source: https://readwise.io/reader_api

The expected JSON response format when successfully querying the tags endpoint.

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

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

### Document BULK UPDATE API

Source: https://readwise.io/reader_api

Use this API to update multiple documents in a single request. Each item in the `updates` array can specify different fields to update. Fields omitted from an item will remain unchanged for that document. Maximum 50 items per request. Rate limit: 20/minute per access token.

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

### Description
Updates multiple documents in a single request. Each item in the `updates` array can specify different fields to update. Fields omitted from an item will remain unchanged for that document.

### Method
PATCH

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

### Parameters
#### Request Body
- **updates** (array) - Required - An array of objects, where each object represents an update for a document.
  - **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.
  - **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 (replaces all existing tags).
  - **notes** (string) - Optional - A string to replace the current document note.

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

### Response
#### Success Response (200)
- **results** (array) - An array of objects indicating the success of each update.
  - **id** (string) - The ID of the document updated.
  - **success** (boolean) - True if the update was successful, false otherwise.
  - **error** (string) - Error message if the update failed.

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

#### Error Responses
- **Status code 207**: Some or all items failed despite having a valid payload — check per-item error messages.
- **Status code 400**: Request payload is incorrect.
```

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

### Document LIST API

Source: https://readwise.io/reader_api

Retrieves a list of documents from your Readwise.io account. Supports filtering by various parameters and pagination.

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

### Description
Retrieves a list of documents from your Readwise.io account. Supports filtering by various parameters and pagination.

### 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 (formatted as ISO 8601 date).
- **location** (string) - Optional - The document's location, could be one of: `new`, `later`, `shortlist`, `archive`, `feed`.
- **category** (string) - Optional - The document's category, could be one of: `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 (`?tag=`) to find untagged documents. Use the Tag LIST endpoint to retrieve all tags available.
- **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. Use it to get the next page of documents if there are too many for one request.
- **withHtmlContent** (boolean) - Optional - Include the `html_content` field in each document's data. Please note that enabling this feature may slightly increase request processing time. Could be one of: `true`, `false`.
- **withRawSourceUrl** (boolean) - Optional - Include the `raw_source_url` field in each document's data, containing a direct Amazon S3 link to the raw document source file. The link is empty for non-distributable documents, like Wisereads previews. The link is valid for one hour. Please note that enabling this feature may slightly increase request processing time. Could be one of: `true`, `false`.

### Response
#### Success Response (200)
- **count** (integer) - The total number of documents matching the query.
- **nextPageCursor** (string) - A string to be used with the `pageCursor` parameter to fetch the next page of results.
- **results** (array) - A list of document objects.
  - **id** (string) - The document's unique id.
  - **url** (string) - The URL to the document within the Readwise.io interface.
  - **source_url** (string) - The original URL of the document.
  - **title** (string) - The title of the document.
  - **author** (string) - The author of the document.
  - **source** (string) - The source of the document (e.g., 'Reader RSS', 'Reader add from import URL').
  - **category** (string) - The category of the document.
  - **location** (string) - The current location of the document (e.g., 'feed', 'new', 'archive').
  - **tags** (object) - An object containing the tags associated with the document.
  - **site_name** (string) - The name of the website where the document originated.
  - **word_count** (integer) - The word count of the document.
  - **reading_time** (string) - Estimated reading time for the document.
  - **created_at** (string) - The date and time the document was created (UTC).
  - **updated_at** (string) - The date and time the document was last updated (UTC).
  - **notes** (string) - Any notes associated with the document.
  - **published_date** (string) - The original publication date of the document.
  - **summary** (string) - A summary or excerpt of the document.
  - **image_url** (string) - A URL to an image associated with the document.
  - **parent_id** (string|null) - The ID of the parent document if this is a highlight or note.
  - **reading_progress** (number) - The user's reading progress for the document (0.0 to 1.0).
  - **first_opened_at** (string|null) - The date and time the document was first opened.
  - **last_opened_at** (string|null) - The date and time the document was last opened.
  - **saved_at** (string) - The date and time the document was saved to Readwise.
  - **last_moved_at** (string) - The date and time the document was last moved between locations.

#### Response Example
```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",
            "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",
            "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"
        }
    ]
}
```
```

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

### Update Document Fields (Python)

Source: https://readwise.io/reader_api

This Python script demonstrates updating document properties like title and location using the requests library. The JSON payload is sent directly in the request.

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

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

### Tag LIST API

Source: https://readwise.io/reader_api

Retrieves a list of all document tags. Supports pagination using the `pageCursor` query parameter.

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

### Description
Retrieves a list of all document tags. Supports pagination using the `pageCursor` query parameter.

### Method
GET

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

### Parameters
#### Query Parameters
- **pageCursor** (string) - Optional - A string returned by a previous request to this endpoint. Use it to get the next page of tags if there are too many for one request.

### Response
#### Success Response (200)
- **count** (integer) - The total number of tags.
- **nextPageCursor** (string) - A cursor for fetching the next page of results, or null if there are no more pages.
- **results** (array) - A list of tag objects.
  - **key** (string) - The unique key identifier for the tag.
  - **name** (string) - The display name of the tag.

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

### Rate Limit
20/minute per access token.
```

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

### Update Document Fields (JavaScript)

Source: https://readwise.io/reader_api

Use this snippet to update document fields such as title and location via AJAX. Ensure to include your access token in the Authorization header.

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

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

### Bulk Update Request Payload

Source: https://readwise.io/reader_api

The JSON structure for the bulk update request, containing an array of document updates.

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

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

### Document DELETE API

Source: https://readwise.io/reader_api

Deletes a specific document from your Readwise library. Rate limit: 20/minute per access token.

```APIDOC
## DELETE /api/v3/delete/{document_id}/

### Description
Deletes a specific document from your Readwise library.

### Method
DELETE

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

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

### Response
#### Success Response (204)
No content is returned upon successful deletion.
```

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

### Document Update API

Source: https://readwise.io/reader_api

This API endpoint allows you to update specific fields of a document. Fields not included in the request will remain unchanged. The endpoint supports PATCH requests.

```APIDOC
## PATCH /api/v3/update/<document_id>/

### Description
Use this API to update specific fields from the list below. Fields omitted from the request will remain unchanged.

### Method
PATCH

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

### Parameters
#### Request Body
- **title** (string) - no - The document's title, it will overwrite the original title of the document
- **author** (string) - no - The document's author, it will overwrite the original author (if found during the parsing step)
- **summary** (string) - no - Summary of the document
- **published_date** (date) - no - 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"
- **image_url** (string) - no - An image URL to use as cover image
- **seen** (boolean) - no - Mark the document as seen/unseen (without deleting it). Setting `true` will populate `first_opened_at` / `last_opened_at`; setting `false` will clear them.
- **location** (string) - no - One of: `new`, `later`, `archive` or `feed`. Represents the current 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.
- **category** (string) - no - One of: `article`, `email`, `rss`, `highlight`, `note`, `pdf`, `epub`, `tweet` or `video`.
- **tags** (list) - no - A list of strings containing tags, example: `["tag1", "tag2"]`
- **notes** (string) - no - A string to replace the current _Document note_ for this document. Pass an empty string to clear the existing note. Note: this field does not work to add notes for highlights.

### Response
#### Success Response (200)
- **id** (string) - The updated document's ID.
- **url** (string) - The URL to the updated document on Readwise.

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

### Rate Limit
50/minute per access token.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.