{"id":10610086,"url":"https://github.com/joshbeckman/readwise-ruby","last_synced_at":"2025-09-03T14:52:53.433Z","repository":{"id":65330704,"uuid":"589730156","full_name":"joshbeckman/readwise-ruby","owner":"joshbeckman","description":"Minimal Readwise API client and highlight parsing library","archived":false,"fork":false,"pushed_at":"2024-05-18T17:18:13.000Z","size":100,"stargazers_count":5,"open_issues_count":4,"forks_count":2,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-12-19T04:39:04.205Z","etag":null,"topics":["gem","readwise","ruby"],"latest_commit_sha":null,"homepage":"https://rubygems.org/gems/readwise","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/joshbeckman.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","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},"funding":{"github":"joshbeckman"}},"created_at":"2023-01-16T19:57:15.000Z","updated_at":"2024-01-20T09:19:42.000Z","dependencies_parsed_at":"2023-07-15T14:11:27.479Z","dependency_job_id":"ac8a7f85-7093-434d-9c83-87a835cf7bc9","html_url":"https://github.com/joshbeckman/readwise-ruby","commit_stats":null,"previous_names":["andjosh/readwise-ruby"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshbeckman%2Freadwise-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshbeckman%2Freadwise-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshbeckman%2Freadwise-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/joshbeckman%2Freadwise-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/joshbeckman","download_url":"https://codeload.github.com/joshbeckman/readwise-ruby/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":232721691,"owners_count":18566452,"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","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":["gem","readwise","ruby"],"created_at":"2024-06-02T09:27:04.903Z","updated_at":"2025-09-03T14:52:53.422Z","avatar_url":"https://github.com/joshbeckman.png","language":"Ruby","funding_links":["https://github.com/sponsors/joshbeckman"],"categories":["Client Libraries"],"sub_categories":[],"readme":"# Readwise\n\n[![Gem Version](https://badge.fury.io/rb/readwise.svg)](https://badge.fury.io/rb/readwise) [![Ruby](https://github.com/joshbeckman/readwise-ruby/actions/workflows/ruby.yml/badge.svg)](https://github.com/joshbeckman/readwise-ruby/actions/workflows/ruby.yml)\n\n[Readwise](https://readwise.io/) is an application suite to store, revisit, and learn from your book and article highlights. This is a basic library to call the [Readwise API](https://readwise.io/api_deets) to read and write highlights, and manage Reader documents through the [Reader API](https://readwise.io/reader_api).\n\nThis library is not at 100% coverage of the API, so if you need a method that is missing, open an issue or contribute changes!\n\n## Installation\n\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'readwise'\n```\n\nAnd then execute:\n\n    $ bundle\n\nOr install it yourself as:\n\n    $ gem install readwise\n\n## Usage\n\nFirst, obtain an API access token from https://readwise.io/access_token.\n\n### Highlights API (V2)\n\nThe [V2 API](https://readwise.io/api_deets) provides access to your highlights and books:\n\n```ruby\nclient = Readwise::Client.new(token: token)\n\nbooks = client.export # export all highlights\nbooks = client.export(updated_after: '2023-01-17T22:02:48Z') # export recent highlights\nbooks = client.export(book_ids: ['123']) # export specific highlights\n\nputs books.first.title # books are Readwise::Book structs\nputs books.first.highlights.map(\u0026:text) # highlights are Readwise::Highlight structs\n\n# create a highlight\ncreate = Readwise::HighlightCreate.new(text: 'foobar', author: 'Joan')\nhighlight = client.create_highlight(highlight: create)\n\n# update a highlight\nupdate = Readwise::HighlightUpdate.new(text: 'foobaz', color: 'yellow')\nupdated = client.update_highlight(highlight: highlight, update: update)\n\n# add a tag to a highlight\ntag = Readwise::Tag.new(name: 'foobar')\nadded_tag = client.add_highlight_tag(highlight: highlight, tag: tag)\n\n# update a tag on a highlight\nadded_tag.name = 'bing'\nupdated_tag = client.update_highlight_tag(highlight: highlight, tag: added_tag)\n\n# remove a tag from a highlight\nclient.remove_highlight_tag(highlight: highlight, tag: added_tag)\n\n# get daily review highlights\ndaily_review = client.daily_review\nputs daily_review.id\nputs daily_review.url\nputs daily_review.completed?\nputs daily_review.highlights.size\nputs daily_review.highlights.first.text\n```\n\n### Reader API (V3)\n\nThe [V3 API](https://readwise.io/reader_api) provides access to Readwise Reader functionality for managing documents (articles, PDFs, etc.):\n\n```ruby\n# Get all documents\ndocuments = client.get_documents\n\n# Get documents with filters\ndocuments = client.get_documents(\n  updated_after: '2023-01-01T00:00:00Z',\n  location: 'new',        # 'new', 'later', 'archive', or 'feed'\n  category: 'article'     # 'article', 'email', 'rss', 'highlight', 'note', 'pdf', 'epub', 'tweet', 'video'\n)\n\n# Get a specific document\ndocument = client.get_document(document_id: '123456')\n\nputs document.title\nputs document.author\nputs document.url\nputs document.reading_progress\nputs document.location\nputs document.category\n\n# Check document properties\nputs document.read?                    # reading progress \u003e= 85%\nputs document.read?(threshold: 0.5)    # custom threshold\nputs document.parent?                  # is this a top-level document?\nputs document.child?                   # is this a highlight/note of another document?\n\n# Check location\nputs document.in_new?\nputs document.in_later?\nputs document.in_archive?\n\n# Check category\nputs document.article?\nputs document.pdf?\nputs document.epub?\nputs document.tweet?\nputs document.video?\nputs document.book?\nputs document.email?\nputs document.rss?\nputs document.highlight?\nputs document.note?\n\n# Access timestamps\nputs document.created_at_time\nputs document.updated_at_time\nputs document.published_date_time\n\n# Create a new document\ndocument_create = Readwise::DocumentCreate.new(\n  url: 'https://example.com/article',\n  title: 'My Article',\n  author: 'John Doe',\n  html: '\u003cp\u003eArticle content\u003c/p\u003e',\n  summary: 'A brief summary',\n  location: 'new',           # 'new', 'later', 'archive', or 'feed'\n  category: 'article',       # 'article', 'email', 'rss', etc.\n  tags: ['technology', 'programming'],\n  notes: 'My personal notes',\n  should_clean_html: true,\n  saved_using: 'api'\n)\n\ndocument = client.create_document(document: document_create)\n\n# Create multiple documents\ndocuments = client.create_documents(documents: [document_create1, document_create2])\n```\n\n## Command Line Interface\n\nThis gem includes a `readwise` command-line tool for quickly sending HTML content to Readwise Reader.\n\nFirst, set your API token:\n```bash\nexport READWISE_API_KEY=your_token_here\n```\n\nThen use the CLI to send HTML files:\n```bash\n# Basic usage\nreadwise document create --html-file content.html\nreadwise document create --url https://datatracker.ietf.org/doc/html/rfc2324\n\n# Short form flag\nreadwise document create -f content.html\n\n# With options\nreadwise document create --html-file content.html --title=\"My Article\" --location=later\n\n# See all available options\nreadwise --help\nreadwise document create --help\n```\n\n## Development\n\nAfter checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.\n\nTo install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).\n\n## Contributing\n\nBug reports and pull requests are welcome on GitHub at https://github.com/joshbeckman/readwise-ruby. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [Contributor Covenant](http://contributor-covenant.org) code of conduct.\n\n## License\n\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n\n## Code of Conduct\n\nEveryone interacting in the Readwise project’s codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/joshbeckman/readwise-ruby/blob/main/CODE_OF_CONDUCT.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshbeckman%2Freadwise-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjoshbeckman%2Freadwise-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjoshbeckman%2Freadwise-ruby/lists"}