The Readwise connector lets your AI agent act in each user's Readwise account. Each user connects their own Readwise API key once, and Scalekit sends it with every call, so your agent never handles credentials. It comes with 27 tools.
- Tools
- 27
- What they doRead · write · destructive
- 11 · 12 · 411 read12 write4 destructive
- Users sign in with
- API key
Setup
Install the SDK
Terminal window npm install @scalekit-sdk/node dotenvTerminal window pip install scalekit-sdk-python python-dotenvSet your credentials
Add your Scalekit credentials to your
.envfile. Find values in app.scalekit.com > Developers > API Credentials..env SCALEKIT_ENVIRONMENT_URL=<your-environment-url>SCALEKIT_CLIENT_ID=<your-client-id>SCALEKIT_CLIENT_SECRET=<your-client-secret>Create the Readwise connection
In AgentKit > Connections, create a Readwise connection. The name you give it is the
connection_nameyour code passes. See Configure connections.Authorize a user and make your first call
quickstart.mts import { ScalekitClient } from '@scalekit-sdk/node'import 'dotenv/config'import { createInterface } from 'node:readline/promises'const scalekit = new ScalekitClient(process.env.SCALEKIT_ENVIRONMENT_URL,process.env.SCALEKIT_CLIENT_ID,process.env.SCALEKIT_CLIENT_SECRET,)const actions = scalekit.actionsconst connector = 'readwise'const identifier = 'user_123'// Generate an authorization link for the userconst { link } = await actions.getAuthorizationLink({ connectionName: connector, identifier })console.log('Authorize Readwise:', link)const rl = createInterface({ input: process.stdin, output: process.stdout })await rl.question('Press Enter after authorizing...')rl.close()// Make your first callconst result = await actions.executeTool({connector,identifier,toolName: 'readwise_check_auth',toolInput: {},})console.log(result)Terminal window npx tsx quickstart.mtsquickstart.py import osfrom scalekit import ScalekitClientfrom dotenv import load_dotenvload_dotenv()scalekit_client = ScalekitClient(env_url=os.getenv("SCALEKIT_ENVIRONMENT_URL"),client_id=os.getenv("SCALEKIT_CLIENT_ID"),client_secret=os.getenv("SCALEKIT_CLIENT_SECRET"),)actions = scalekit_client.actionsconnection_name = "readwise"identifier = "user_123"# Generate an authorization link for the userlink_response = actions.get_authorization_link(connection_name=connection_name,identifier=identifier,)print("Authorize Readwise:", link_response.link)input("Press Enter after authorizing...")# Make your first callresult = actions.execute_tool(tool_input={},tool_name="readwise_check_auth",connection_name=connection_name,identifier=identifier,)print(result)Terminal window python quickstart.pyEach user opens the link once and enters their Readwise credentials there. See Authorize a user for the full flow and statuses.
Tools
Pass the exact name toexecute_toolreadwise_check_authVerify that the connected Readwise access token is valid.Read-onlyCheck Authentication
Verify that the connected Readwise access token is valid. Returns an empty response with HTTP 204 when the token is valid and an auth error otherwise. Use it to diagnose authentication failures before calling other tools.
Inputs
This tool takes no inputs.
readwise_export_highlightsExport the user's books, articles and podcasts with all of their highlights nested inside.Read-onlyExport Highlights
Export the user's books, articles and podcasts with all of their highlights nested inside. Returns count, nextPageCursor and results; each result has user_book_id, title, author, category, source, tags and a highlights array with text, note, location, color and tags. Use it to pull everything in one pass or only what changed since updatedAfter. Use list_highlights for a flat, filterable list of highlights and list_books for sources without highlights.
Inputs
idsstring- Comma-separated list of user_book_ids; returns all highlights for only these books. Example: 123,456.
includeDeletedboolean- Set true to include deleted highlights so you can sync deletions. Omit to exclude them.
pageCursorstring- The nextPageCursor value from a previous response, used to fetch the next page. Omit on the first request.
updatedAfterstring- Only return highlights updated after this ISO 8601 datetime (UTC). Use the time of your last sync for incremental pulls. Example: 2024-01-01T00:00:00Z.
readwise_get_bookRetrieve one book, article, tweet or podcast by id.Read-onlyGet Book
Retrieve one book, article, tweet or podcast by id. Returns id, title, author, category, source, num_highlights, last_highlight_at, updated, cover_image_url, highlights_url, source_url, asin, tags and document_note. Use it when you already have a book id. Use list_books to find ids.
Inputs
book_idintegerrequired- ID of the book, article or podcast, as returned by list_books. Example: 1776.
readwise_get_daily_reviewFetch the highlights in the user's latest Readwise daily review.Read-onlyGet Daily Review
Fetch the highlights in the user's latest Readwise daily review. Returns review_id, review_url, review_completed and a highlights array with text, title, author, note, location and id. Responds 404 with detail Review not found when no daily review exists. Use it to surface today's resurfaced highlights. Use complete_daily_review to mark the review done.
Inputs
This tool takes no inputs.
readwise_get_highlightRetrieve one highlight by id.Read-onlyGet Highlight
Retrieve one highlight by id. Returns id, text, note, location, location_type, highlighted_at, created_at, url, color, updated, book_id, external_id, tags, end_location and readwise_url. Use it when you already have a highlight id. Use list_highlights to find ids.
Inputs
highlight_idintegerrequired- ID of the highlight, as returned by list_highlights or export_highlights. Example: 59758950.
readwise_list_booksList the user's sources (books, articles, tweets, podcasts and supplementals) with highlight counts.Read-onlyList Books
List the user's sources (books, articles, tweets, podcasts and supplementals) with highlight counts. Returns count, next, previous and results; each result has id, title, author, category, source, num_highlights, last_highlight_at, updated, cover_image_url, highlights_url, source_url, asin and tags. Use it to browse sources or find a book id. Use list_highlights with book_id for the highlights themselves. This endpoint is limited to 20 requests per minute.
Inputs
categorystring- Return only sources in this category. One of books, articles, tweets, supplementals or podcasts.one of
booksarticlestweetssupplementalspodcasts last_highlight_at__gtstring- Only sources whose last highlight was taken after this ISO 8601 datetime. Some sources have no value. Example: 2024-01-01T00:00:00Z.
last_highlight_at__ltstring- Only sources whose last highlight was taken before this ISO 8601 datetime. Some sources have no value. Example: 2024-06-01T00:00:00Z.
pageinteger- Page number to fetch, starting at 1. Increase it to walk through paginated books; the response's next field links to the following page. Example: 2.
page_sizeinteger- Number of books to return per page. Defaults to 100 when omitted, maximum 1000. Example: 50.
sourcestring- Return only sources imported from this origin. Example: kindle.
updated__gtstring- Only sources last updated after this ISO 8601 datetime. Example: 2024-01-01T00:00:00Z.
updated__ltstring- Only sources last updated before this ISO 8601 datetime. Example: 2024-06-01T00:00:00Z.
readwise_list_highlightsList the user's highlights as a flat, paginated list, optionally filtered by book or by time.Read-onlyList Highlights
List the user's highlights as a flat, paginated list, optionally filtered by book or by time. Returns count, next, previous and results; each result has id, text, note, location, location_type, highlighted_at, color, book_id, tags and readwise_url. Use it to browse or filter highlights. Use export_highlights to get highlights grouped under their books, and get_highlight for one highlight by id. This endpoint is limited to 20 requests per minute.
Inputs
book_idinteger- Return only highlights of this book. Get book ids from list_books. Example: 1337.
highlighted_at__gtstring- Only highlights taken after this ISO 8601 datetime. Some highlights have no highlighted_at value. Example: 2020-02-01T21:35:53Z.
highlighted_at__ltstring- Only highlights taken before this ISO 8601 datetime. Some highlights have no highlighted_at value. Example: 2024-06-01T00:00:00Z.
pageinteger- Page number to fetch, starting at 1. Increase it to walk through paginated highlights; the response's next field links to the following page. Example: 2.
page_sizeinteger- Number of highlights to return per page. Defaults to 100 when omitted, maximum 1000. Example: 50.
updated__gtstring- Only highlights last updated after this ISO 8601 datetime. Example: 2024-01-01T00:00:00Z.
updated__ltstring- Only highlights last updated before this ISO 8601 datetime. Example: 2024-06-01T00:00:00Z.
readwise_reader_list_documentsList documents in the user's Reader library, with filters for location, category, tag and update time.Read-onlyList Reader Documents
List documents in the user's Reader library, with filters for location, category, tag and update time. Returns count, nextPageCursor and results; each result has id, url, source_url, title, author, category, location, tags, word_count, reading_progress, notes, summary and saved_at. Highlights and notes appear as documents with parent_id set. Use it to browse or sync Reader, or to fetch one document by id. Use reader_list_tags to see tag keys. Limited to 20 requests per minute.
Inputs
categorystring- Document category. One of article, email, rss, highlight, note, pdf, epub, tweet, video.one of
articleemailrsshighlightnotepdfepubtweetvideo idstring- Return only the document with this id, if found. Example: 01gwfvp9pyaabcdgmx14f6ha0.
limitinteger- Maximum number of documents to return, between 1 and 100. Defaults to 100. Example: 25.
locationstring- Return only documents in this location. One of new, later, shortlist, archive, feed. If the user has not enabled that location in Reader settings, their default location is used.one of
newlatershortlistarchivefeed pageCursorstring- The nextPageCursor value from a previous response, used to fetch the next page. Omit on the first request.
tagstring- A tag key to filter by, as returned by reader_list_tags. Example: reading-list.
updatedAfterstring- Only documents updated after this ISO 8601 datetime (UTC). Example: 2024-01-01T00:00:00Z.
withHtmlContentboolean- Set true to include the html_content field in each document. This can slow the request slightly.
withRawSourceUrlboolean- Set true to include raw_source_url, a link to the raw source file that is valid for one hour. Empty for non-distributable documents.
readwise_complete_daily_reviewMark the user's current Readwise daily review as complete.WriteComplete Daily Review
Mark the user's current Readwise daily review as complete. Returns review_id and review_completed set to true. Use it after the highlights from get_daily_review have been shown to the user.
Inputs
This tool takes no inputs.
readwise_create_book_tagAdd a tag to a book, article or podcast.WriteCreate Book Tag
Add a tag to a book, article or podcast. Returns the tag with its id and name. Use it to tag a whole source. Use create_highlight_tag to tag a single highlight.
Inputs
book_idintegerrequired- ID of the book, article or podcast, as returned by list_books. Example: 1776.
namestringrequired- Name of the tag. Maximum 512 characters. Example: philosophy.
readwise_create_highlight_tagAdd a tag to a highlight.WriteCreate Highlight Tag
Add a tag to a highlight. Returns the tag with its id and name. Use it to tag a single highlight. Use create_book_tag to tag a whole book.
Inputs
highlight_idintegerrequired- ID of the highlight, as returned by list_highlights or export_highlights. Example: 59758950.
namestringrequired- Name of the tag. Maximum 127 characters. Example: philosophy.
readwise_create_highlightsSave one or more highlights, with their source book, article or podcast, to the user's Readwise library.WriteCreate Highlights
Save one or more highlights, with their source book, article or podcast, to the user's Readwise library. Returns the list of created or updated sources, each with its id, title, num_highlights and modified_highlights (the ids of the highlights this request created or updated). Use it to add or upsert highlights from your own app. Readwise de-duplicates by title, author, text and source_url, and updates a highlight when the same highlight_url is sent with new text. Use update_highlight to edit a highlight by id.
Inputs
highlightsarrayrequired- Array of highlight objects to save, 1 or more, from the same or different sources. Each needs text; title, author, source_url, source_type, category, note, location, location_type, highlighted_at, highlight_url and image_url are optional. Example: [{"text": "Call me Ishmael", "title": "Moby Dick", "author": "Herman Melville", "category": "books"}].
readwise_reader_bulk_update_documentsUpdate up to 50 Reader documents in one request, each with its own fields.WriteBulk Update Reader Documents
Update up to 50 Reader documents in one request, each with its own fields. Returns a results array with an id and success flag per item, plus an error message on failures. The status is 200 when all succeed and 207 when some items fail. Use it to archive, tag or move many documents at once. Use reader_update_document for a single document. Limited to 20 requests per minute.
- Idempotent
Inputs
updatesarrayrequired- Array of up to 50 update objects. Each needs the document id and any of title, author, summary, language, published_date, image_url, seen, location, category, tags and notes; tags replace all existing tags. Example: [{"id": "abc123", "location": "archive", "seen": true}, {"id": "def456", "tags": ["reading-list"]}].
readwise_reader_create_highlightCreate a highlight, with an optional note and tags, on a document already saved in Reader.WriteCreate Reader Highlight
Create a highlight, with an optional note and tags, on a document already saved in Reader. Returns the new highlight's id and its Reader url. The request fails with 400 and creates nothing when content is not found in the document. Use it to highlight text in a Reader document. Use create_highlights to add highlights to the Readwise library from an outside source.
Inputs
contentstringrequired- The passage to highlight, exactly as it reads in the parent document's content. Fetch the content with reader_list_documents and with_html_content set to true. Example: the passage, exactly as it appears in the document.
parent_idstringrequired- ID of the Reader document to highlight. Example: 01gwfvp9pyaabcdgmx14f6ha0.
notesstring- A note to attach to the highlight. Example: Great point about incentives.
tagsarray- List of tag names to attach to the highlight. Example: ["reading-list", "ai"].
readwise_reader_save_documentSave a URL, or your own HTML, to the user's Reader library as a new document.WriteSave Document to Reader
Save a URL, or your own HTML, to the user's Reader library as a new document. Returns the document id and its Reader url; the status is 201 for a new document and 200 when it already exists. Use it to add articles, PDFs or any web page to Reader. Use reader_create_highlight to highlight text in a document that is already saved. Limited to 50 requests per minute.
Inputs
urlstringrequired- The document's unique URL. If you have none, use a made-up value such as https://yourapp.com#document1. Example: https://example.com/article/.
authorstring- Author of the document; overrides the author found while parsing. Example: Paul Graham.
categorystring- Document category. One of article, email, rss, pdf, epub, tweet, video.one of
articleemailrsspdfepubtweetvideo htmlstring- The document content as valid HTML. When omitted, Reader scrapes the URL to fetch the content. Example: <div><h1>Title</h1><p>Content</p></div>.
image_urlstring- URL of an image to use as the cover image. Example: https://example.com/cover.png.
languagestring- Language code of the document, such as en, de or en-US. Reader auto-detects it when omitted and uses it for text-to-speech.
locationstring- Initial location of the document. Defaults to new. One of new, later, archive, feed. If the user has not enabled that location in Reader settings, their default location is used.one of
newlaterarchivefeed notesstring- A top-level note on the document. Example: Read before Friday's meeting.
published_datestring- When the document was published, as an ISO 8601 datetime (UTC by default). Example: 2020-07-14T20:11:24+00:00.
saved_usingstring- Label for the source that saved the document, such as the name of your app. Example: my_app.
should_clean_htmlboolean- Only valid when html is provided. Set true to have Reader clean the HTML and parse the title and author. Defaults to false.
summarystring- Short summary of the document. Example: An essay on finding work you love.
tagsarray- List of tag names to attach to the document. Example: ["reading-list", "ai"].
titlestring- Title of the document; overrides the title found while parsing. Example: How to Do What You Love.
readwise_reader_update_documentUpdate fields on a Reader document, such as its title, location, tags, notes or seen state.WriteUpdate Reader Document
Update fields on a Reader document, such as its title, location, tags, notes or seen state. Returns the document id and its Reader url. Omitted fields stay unchanged; on a highlight only notes and tags are accepted. Use it to edit or move one document, for example to archive it. Use reader_bulk_update_documents to change many at once. Limited to 50 requests per minute.
- Idempotent
Inputs
document_idstringrequired- ID of the Reader document, as returned by reader_list_documents or reader_save_document. Example: 01gwfvp9pyaabcdgmx14f6ha0.
authorstring- New author of the document. Example: Paul Graham.
categorystring- Document category. One of article, email, rss, highlight, note, pdf, epub, tweet, video.one of
articleemailrsshighlightnotepdfepubtweetvideo image_urlstring- URL of the cover image. Example: https://example.com/cover.png.
languagestring- Language code of the document, such as en, de or en-US.
locationstring- Move the document to this location. One of new, later, archive, feed. If the user has not enabled that location in Reader settings, their default location is used.one of
newlaterarchivefeed notesstring- Text that replaces the document's current note, or a highlight's note. Send an empty string to clear it. Example: Follow up next week.
published_datestring- Publication datetime as ISO 8601 (UTC by default). Example: 2020-07-14T20:11:24+00:00.
seenboolean- Set true to mark the document as seen, which fills first_opened_at and last_opened_at, or false to mark it unseen and clear them.
summarystring- New summary of the document. Example: An essay on finding work you love.
tagsarray- List of tag names to set on the document, replacing its current tags. Example: ["reading-list", "ai"].
titlestring- New title of the document. Example: Updated title.
readwise_update_bookOverride the title, author or category of a book, article or podcast.WriteUpdate Book
Override the title, author or category of a book, article or podcast. Returns the updated book with id, title, author, category, num_highlights and cover_image_url. Use it to correct source metadata. Send only the fields to change. Cover image upload is not supported by this tool.
- Idempotent
Inputs
book_idintegerrequired- ID of the book, article or podcast, as returned by list_books. Example: 1776.
author_overridestring- A new author shown in place of the original author. Example: Jacob Lund Fisker.
categorystring- New category of the source. One of books, articles, tweets or podcasts.one of
booksarticlestweetspodcasts title_overridestring- A new title shown in place of the original title. Example: Early Retirement Extreme: A Guide.
readwise_update_book_tagRename a tag on a book, article or podcast.WriteUpdate Book Tag
Rename a tag on a book, article or podcast. Returns the updated tag with its id and name. Use it to change a tag's text; get the tag id from list_book_tags.
- Idempotent
Inputs
book_idintegerrequired- ID of the book, article or podcast, as returned by list_books. Example: 1776.
namestringrequired- Name of the tag. Maximum 512 characters. Example: philosophy.
tag_idintegerrequired- ID of the tag, as returned by the list tags tool for this highlight or book. Example: 11311390.
readwise_update_highlightUpdate the text, note, location, url or color of an existing highlight.WriteUpdate Highlight
Update the text, note, location, url or color of an existing highlight. Returns the updated highlight with id, text, note, location, color, book_id, tags and readwise_url. Use it to edit a highlight by id. Send only the fields to change. Use create_highlights to add new highlights.
- Idempotent
Inputs
highlight_idintegerrequired- ID of the highlight, as returned by list_highlights or export_highlights. Example: 59758950.
colorstring- Color tag of the highlight. One of yellow, blue, pink, orange, green or purple.one of
yellowbluepinkorangegreenpurple locationinteger- New position of the highlight in the source, used to order highlights. Example: 57.
notestring- New annotation note for the highlight. Example: This makes me think of Marcus Aurelius.
textstring- New text of the highlight. Example: To be alone for any length of time is to shed an outer skin.
urlstring- Unique URL of the specific highlight, such as one tweet or podcast snippet. Example: https://example.com/post#h1.
readwise_update_highlight_tagRename a tag on a highlight.WriteUpdate Highlight Tag
Rename a tag on a highlight. Returns the updated tag with its id and name. Use it to change a tag's text; get the tag id from list_highlight_tags.
- Idempotent
Inputs
highlight_idintegerrequired- ID of the highlight, as returned by list_highlights or export_highlights. Example: 59758950.
namestringrequired- Name of the tag. Maximum 127 characters. Example: philosophy.
tag_idintegerrequired- ID of the tag, as returned by the list tags tool for this highlight or book. Example: 11311390.
readwise_delete_book_tagRemove a tag from a book, article or podcast.DestructiveDelete Book Tag
Remove a tag from a book, article or podcast. Returns an empty response with HTTP 204 on success. Use it to untag a source; get the tag id from list_book_tags.
- Idempotent
Inputs
book_idintegerrequired- ID of the book, article or podcast, as returned by list_books. Example: 1776.
tag_idintegerrequired- ID of the tag, as returned by the list tags tool for this highlight or book. Example: 11311390.
readwise_delete_highlightPermanently delete a highlight by id.DestructiveDelete Highlight
Permanently delete a highlight by id. Returns an empty response with HTTP 204 on success. Use it only when the user wants the highlight removed. Use update_highlight to change it instead.
- Idempotent
Inputs
highlight_idintegerrequired- ID of the highlight, as returned by list_highlights or export_highlights. Example: 59758950.
readwise_delete_highlight_tagRemove a tag from a highlight.DestructiveDelete Highlight Tag
Remove a tag from a highlight. Returns an empty response with HTTP 204 on success. Use it to untag a highlight; get the tag id from list_highlight_tags.
- Idempotent
Inputs
highlight_idintegerrequired- ID of the highlight, as returned by list_highlights or export_highlights. Example: 59758950.
tag_idintegerrequired- ID of the tag, as returned by the list tags tool for this highlight or book. Example: 11311390.
readwise_reader_delete_documentPermanently delete a Reader document, including its highlights and their notes.DestructiveDelete Reader Document
Permanently delete a Reader document, including its highlights and their notes. Returns an empty response with HTTP 204 on success. Use it only when the user wants the document gone; use reader_update_document with location archive to keep it. Deleting a highlight also deletes its note. Limited to 20 requests per minute.
- Idempotent
Inputs
document_idstringrequired- ID of the Reader document, as returned by reader_list_documents or reader_save_document. Example: 01gwfvp9pyaabcdgmx14f6ha0.
No tools match.
