{"id":20208426,"url":"https://github.com/scarvy/readwise-reader-api","last_synced_at":"2025-07-31T10:09:43.770Z","repository":{"id":216998199,"uuid":"742625740","full_name":"Scarvy/readwise-reader-api","owner":"Scarvy","description":"An unofficial JS/TS client for the Readwise Reader API 📚","archived":false,"fork":false,"pushed_at":"2024-08-20T18:29:18.000Z","size":844,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-05T13:41:13.417Z","etag":null,"topics":["api-client","javascript","readwise","readwise-reader","typescript"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"isc","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Scarvy.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-12T22:37:30.000Z","updated_at":"2025-04-12T03:06:23.000Z","dependencies_parsed_at":null,"dependency_job_id":"4c40ce69-aa96-424a-9fb5-1c7025f9df8b","html_url":"https://github.com/Scarvy/readwise-reader-api","commit_stats":null,"previous_names":["scarvy/readwise-reader-api"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Scarvy/readwise-reader-api","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Scarvy%2Freadwise-reader-api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Scarvy%2Freadwise-reader-api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Scarvy%2Freadwise-reader-api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Scarvy%2Freadwise-reader-api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Scarvy","download_url":"https://codeload.github.com/Scarvy/readwise-reader-api/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Scarvy%2Freadwise-reader-api/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":268022107,"owners_count":24182803,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-31T02:00:08.723Z","response_time":66,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","javascript","readwise","readwise-reader","typescript"],"created_at":"2024-11-14T05:35:32.383Z","updated_at":"2025-07-31T10:09:43.722Z","avatar_url":"https://github.com/Scarvy.png","language":"TypeScript","readme":"# An unofficial Readwise \u0026 Reader SDK for JavaScript\n\nThis client provides a convenient way to interact with the Readwise \u0026 Reader API, suitable for both JavaScript and TypeScript applications.\n\n## Installation\n\n```bash\nnpm install readwise-reader-api\n```\n\n## Usage\n\n### Prerequisites\n\n1. Obtain a Readwise API token [here](https://readwise.io/access_token)\n2. Store in .env file or in an environment variable.\n\n```bash\nexport READWISE_TOKEN=\u003capi_token\u003e\n```\n\nImport and initialize a client (`Readwise` or `Reader`) using an access token.\n\n```typescript\nimport { Readwise } from \"readwise-reader-api\";\n\nconst readwise = new Readwise({\n  auth: process.env.READWISE_TOKEN,\n});\n```\n\nMake a request to any Readwise (or Reader) API endpoint.\n\n\u003e See the complete list of endpoints in the API Reference:\n\u003e\n\u003e - [Readwise](https://readwise.io/api_deets)\n\u003e - [Readwise Reader](https://readwise.io/reader_api)\n\n```javascript\n(async () =\u003e {\n  const daily_review = await readwise.review.daily();\n})();\n```\n\nEach method returns a `Promise` which resolves the response.\n\n```javascript\nconsole.log(daily_review);\n```\n\n```bash\n{\n  review_id: 104932226,\n  review_url: 'https://readwise.io/reviews/104932226',\n  review_completed: true,\n  highlights: [\n    {\n      text: '“If it walks like a duck and it quacks like a duck, then it must be a duck.”',\n      title: 'Practices of the Python Pro',\n      author: 'Dane Hillard',\n      url: null,\n      source_url: 'https://read.readwise.io/read/01h65f61js5qpaycd1409e22qw',\n      source_type: 'article',\n      category: null,\n      location_type: 'offset',\n      location: 78999682,\n      note: '',\n      highlighted_at: '2023-09-17T15:46:42.883825Z',\n      highlight_url: 'https://read.readwise.io/read/01hahx56818mje85sga832j5t2',\n      image_url: 'https://readwise-assets.s3.amazonaws.com/static/images/article0.00998d930354.png',\n      id: 597114893,\n      api_source: null\n    },\n    ...\n    {\n      text: 'we continue along this rate of change and follow a “Large Model Moore’s Law,” then these far-fetched scenarios may just enter the realm of the possible.',\n      title: 'Generative AI: A Creative New World',\n      author: 'Sonya Huang',\n      url: null,\n      source_url: 'https://read.readwise.io/read/01h6qabyzghazrt1qsjvf9zeqa',\n      source_type: 'article',\n      category: null,\n      location_type: 'offset',\n      location: 21926,\n      note: '',\n      highlighted_at: '2023-08-04T15:17:58.196413Z',\n      highlight_url: 'https://read.readwise.io/read/01h70j0xryxnwm3b6wcf4n6kfh',\n      image_url: 'https://www.sequoiacap.com/wp-content/uploads/sites/6/2022/09/robots-1-1960.jpg',\n      id: 574654751,\n      api_source: null\n    },\n  ]\n}\n```\n\n## Client Library References\n\nA reference for all methods and types available in Readwise and Reader Client libraries.\n\n### Readwise\n\n**EXPORT Highlights**: Export all highlights after a specific date.\n\n```typescript\nasync function exportHighlights() {\n  try {\n    const highlights: ReadwiseBookHighlights[] =\n      await readwise.highlights.export({\n        updatedAfter: \"2024-01-27T00:00:00Z\",\n      });\n    console.log(highlights);\n  } catch (error) {\n    console.error(\"Error:\", error);\n  }\n}\n```\n\n**LIST Highlights**: List all highlights after a specific date.\n\n```typescript\nasync function listHighlights() {\n  try {\n    const highlights: ReadwiseHighlight[] = await readwise.highlights.list({\n      highlighted_at__gt: \"2024-01-27T00:00:00Z\",\n    });\n    console.log(highlights);\n  } catch (error) {\n    console.error(\"Error:\", error);\n  }\n}\n```\n\n**DAILY REVIEW:** Returns your daily review highlights.\n\n```typescript\nasync function getDailyReview() {\n  /** Get Daily Review */\n  try {\n    const review = await readwise.review.daily();\n    console.log(review);\n  } catch (error) {\n    console.error(\"Error:\", error);\n  }\n}\n```\n\n**DETAILS Book:** Get details for a book (eg Article, Blog, Tweet, Book, etc.).\n\n```typescript\nasync function getBookDetails() {\n  try {\n    const book: ReadwiseBook = await readwise.books.details({\n      book_id: \"35943114\",\n    });\n    console.log(book);\n  } catch (error) {\n    console.error(\"Error:\", error);\n  }\n}\n```\n\n**LIST Highlights (in Book):** Get all highlights for a single book (eg Article, Blog, Tweet, Book, etc.).\n\n```typescript\nasync function getBookHighlights() {\n  try {\n    const book_highlights: ReadwiseHighlight[] = await readwise.highlights.list(\n      { book_id: 35943114 },\n    );\n    console.log(book_highlights);\n  } catch (error) {\n    console.error(\"Error:\", error);\n  }\n}\n```\n\n**EXPORT Highlights (in Book):** Export all highlights for a single book (eg Article, Blog, Tweet, Book, etc.).\n\n```typescript\nasync function exportBookHighlights(): Promise\u003cvoid\u003e {\n  try {\n    const highlights: ReadwiseBookHighlights[] =\n      await readwise.highlights.export({ ids: 35943114 });\n    console.log(highlights);\n  } catch (error) {\n    console.error(\"Error:\", error);\n  }\n}\n```\n\n### Advanced Usage\n\nGet all highlights for a particular category (eg \"Tweets\")\n\n```typescript\nasync function getHighlightsFromTweets() {\n  const books: ReadwiseBook[] = await readwise.books.list({\n    category: \"tweets\",\n  });\n  for (const book of books) {\n    const highlights = await readwise.highlights.list({ book_id: book.id });\n    if (highlights.length \u003e 0) {\n      console.log(book.title);\n      for (const highlight of highlights) {\n        console.log(highlight.text);\n      }\n    }\n  }\n}\n```\n\n### Readwise Reader\n\nProvides the ability to create, list, and retrieve documents.\n\n```typescript\nimport { Reader } from 'readwise-reader-api\n\nconst reader = new Reader({\n  auth: process.env.READWISE_TOKEN,\n});\n```\n\n**CREATE Document:** Create a document.\n\n```typescript\nconst result = await reader.document.create({\n  url: url,\n  title: \"New Title\",\n});\n```\n\nThe response will show if document already exists or not.\n\n```bash\n{\n  document_already_exists: true,\n  data: {\n    id: '01hqeecsxa5qx6beyjvbrz37e4',\n    url: 'https://read.readwise.io/read/01hqeecsxa5qx6beyjvbrz37e4'\n  }\n}\n```\n\n**LIST Documents:** List documents for a specific _location_, _category_ and/or _date_.\n\n```typescript\nasync function listReaderDocuments() {\n  try {\n    console.log(\"Getting documents...\");\n    const docs = await reader.document.list(\n      \"new\",\n      \"article\",\n      \"2024-01-01T00:00:00Z\",\n    );\n    console.log(docs);\n  } catch (error) {\n    console.error(\"Error:\", error);\n  }\n}\n```\n\n**GET Document by ID:** Retrieve a single document.\n\n```typescript\nasync function getReaderDocument() {\n  try {\n    console.log(\"Getting a specific document...\");\n    const doc = await reader.document.id(\"01hkwssvj7g207daxvk5k1tc4d\");\n    console.log(doc);\n  } catch (error) {\n    console.error(\"Error:\", error);\n  }\n}\n```\n\n### Available Readwise and Reader Types\n\n```typescript\nexport {\n  /** Readwise */\n  ReadwiseBook,\n  ReadwiseBookHighlights,\n  ReadwiseHighlight,\n  ReadwiseLibraryCategoryType,\n  /** Reader */\n  ReaderDocument,\n  ReaderLocationType,\n  ReaderCategoryType,\n} from \"./api-endpoints\";\n```\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscarvy%2Freadwise-reader-api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fscarvy%2Freadwise-reader-api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fscarvy%2Freadwise-reader-api/lists"}