{"openapi":"3.1.0","info":{"title":"Readwise (BYOK) API","version":"0.1.0","description":"Readwise (BYOK) lets an AI assistant read your own Readwise data through the Readwise API with a key you supply (access token). Read-only: 9 tools (list_highlights, list_books, get_book, export_highlights, get_daily_review, list_highlight_tags, list_book_tags, reader_list_documents, reader_list_tags). The BYOK key travels with each request, is used for that one call only and is never stored,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-readwise.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-readwise/docs"},"termsOfService":"https://connectorbay.com/byok-readwise/terms"},"servers":[{"url":"https://byok-readwise.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-readwise/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_highlights":{"post":{"operationId":"list_highlights","summary":"List your Readwise highlights, 100 per page at most, optionally for one book or changed after a date. Returns text, note","description":"List your Readwise highlights, 100 per page at most, optionally for one book or changed after a date. Returns text, note, location, colour, tags and book id. Readwise limits this call to 20 per minute. Use for \"What are my most recent Readwise highlights\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"book_id":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"default":null,"description":"Only highlights of this book (the id from list_books).","title":"Book Id"},"highlighted_at_gt":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only highlights made after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Highlighted At Gt"},"highlighted_at_lt":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only highlights made before this ISO 8601 time.","title":"Highlighted At Lt"},"updated_gt":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only highlights updated after this ISO 8601 time.","title":"Updated Gt"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Results per page (1 to 100 in this connector; Readwise allows up to 1000).","title":"Page Size"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_highlightsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_books":{"post":{"operationId":"list_books","summary":"List the books, articles, tweets, podcasts and other sources in your Readwise library with author, category, highlight c","description":"List the books, articles, tweets, podcasts and other sources in your Readwise library with author, category, highlight count and last highlight time. Readwise limits this call to 20 per minute. Use for \"Which books do I have the most highlights in on Readwise\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"category":{"anyOf":[{"enum":["books","articles","tweets","supplementals","podcasts"],"type":"string"},{"type":"null"}],"default":null,"description":"Only this kind of source: books, articles, tweets, supplementals or podcasts.","title":"Category"},"source":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only this import source, for example 'kindle' or 'instapaper'.","title":"Source"},"last_highlight_at_gt":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only sources highlighted after this ISO 8601 time.","title":"Last Highlight At Gt"},"updated_gt":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only sources updated after this ISO 8601 time.","title":"Updated Gt"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Results per page (1 to 100 in this connector; Readwise allows up to 1000).","title":"Page Size"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_booksArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_book":{"post":{"operationId":"get_book","summary":"Get one source (book, article, podcast) from your Readwise library: title, author, category, highlight count, source URL","description":"Get one source (book, article, podcast) from your Readwise library: title, author, category, highlight count, source URL and tags. Use for \"Tell me about Readwise book 12345\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"book_id":{"description":"Numeric Readwise book id (the id field from list_books).","minimum":1,"title":"Book Id","type":"integer"}},"required":["book_id"],"title":"get_bookArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/export_highlights":{"post":{"operationId":"export_highlights","summary":"Export highlights grouped by book in pages: each entry has book title, author, category, tags and all its highlights. Us","description":"Export highlights grouped by book in pages: each entry has book title, author, category, tags and all its highlights. Use updatedAfter to fetch only changes; follow nextPageCursor for more pages. Use for \"Export my Readwise highlights from this year grouped by book\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"updated_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only books with highlights changed after this ISO 8601 time, for example 2026-01-01T00:00:00Z.","title":"Updated After"},"ids":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated user_book_ids to export, for example '123,456'.","title":"Ids"},"page_cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"The nextPageCursor value from the previous page to get the next one.","title":"Page Cursor"}},"title":"export_highlightsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_daily_review":{"post":{"operationId":"get_daily_review","summary":"Show today's Readwise daily review: the highlights chosen for review and whether the review is completed. Answers 404 wh","description":"Show today's Readwise daily review: the highlights chosen for review and whether the review is completed. Answers 404 when no review exists yet. Use for \"What is in my Readwise daily review today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_daily_reviewArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_highlight_tags":{"post":{"operationId":"list_highlight_tags","summary":"List the tags on one Readwise highlight. Use for \"Which tags does my Readwise highlight 98765 have\".","description":"List the tags on one Readwise highlight. Use for \"Which tags does my Readwise highlight 98765 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"highlight_id":{"description":"Numeric highlight id (the id field from list_highlights).","minimum":1,"title":"Highlight Id","type":"integer"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Results per page (1 to 100 in this connector; Readwise allows up to 1000).","title":"Page Size"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["highlight_id"],"title":"list_highlight_tagsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_book_tags":{"post":{"operationId":"list_book_tags","summary":"List the tags on one source (book, article) in your Readwise library. Use for \"Which tags does my Readwise book 12345 ha","description":"List the tags on one source (book, article) in your Readwise library. Use for \"Which tags does my Readwise book 12345 have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"book_id":{"description":"Numeric Readwise book id (the id field from list_books).","minimum":1,"title":"Book Id","type":"integer"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":50,"description":"Results per page (1 to 100 in this connector; Readwise allows up to 1000).","title":"Page Size"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["book_id"],"title":"list_book_tagsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/reader_list_documents":{"post":{"operationId":"reader_list_documents","summary":"List documents in your Readwise Reader library (articles, PDFs, emails, RSS, videos) with location, tags, reading progre","description":"List documents in your Readwise Reader library (articles, PDFs, emails, RSS, videos) with location, tags, reading progress and summary, 100 per page at most. Highlights and notes appear as documents with parent_id set. Limited to 20 requests per minute. Use for \"What articles are in my Reader later list\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"location":{"anyOf":[{"enum":["new","later","shortlist","archive","feed"],"type":"string"},{"type":"null"}],"default":null,"description":"Where the document sits: new, later, shortlist, archive or feed.","title":"Location"},"category":{"anyOf":[{"enum":["article","email","rss","highlight","note","pdf","epub","tweet","video"],"type":"string"},{"type":"null"}],"default":null,"description":"Kind of document.","title":"Category"},"tag":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Tag key to require (see reader_list_tags); an empty value returns untagged documents.","title":"Tag"},"updated_after":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only documents updated after this ISO 8601 time.","title":"Updated After"},"id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Return only the document with this id.","title":"Id"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":30,"description":"Documents per page (1 to 100).","title":"Limit"},"page_cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"The nextPageCursor value from the previous page to get the next one.","title":"Page Cursor"}},"title":"reader_list_documentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/reader_list_tags":{"post":{"operationId":"reader_list_tags","summary":"List the tags used in your Readwise Reader library with their key and name. The key is what reader_list_documents takes ","description":"List the tags used in your Readwise Reader library with their key and name. The key is what reader_list_documents takes as tag. Use for \"Which tags do I use in Readwise Reader\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page_cursor":{"anyOf":[{"maxLength":500,"type":"string"},{"type":"null"}],"default":null,"description":"The nextPageCursor value from the previous page to get the next one.","title":"Page Cursor"}},"title":"reader_list_tagsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}