HydrusAPI

HydrusAPI is an implementation of the Hydrus client API in JavaScript. The goal is to fully support the most recent version of the Hydrus client API in a typed, tested, and documented implementation. It was original based off of hydrus.js, but it has drastically deviated from that project and should not be used as a drop in replacement.

As of currently most Hydrus API endpoints are implemented and all the API endpoints supported by hydrus.js are implemented. A list of implemented endpoints are provided at the bottom of this page.

Installation

Package manager users

If you are using npm (or an alternative) package manager then installation is as simple as npm install [email protected].*.

You should always pin the version of HydrusAPI that you are using. See versioning below for more information.

If using an alternative package manager you should replace npm install with your package mangagers install command.

Other users

For other users you can download from the releases page.

Documentation and Usage

HydrusAPI currently doesn't have any documentation or usage instructions. Your best option at the moment is to look at how the tests are implemented.

Contributing

Contributions are greatly appreciated. These can come in the form of reporting issues and creating pull requests. If you have working knowledge of JavaScript and want to contribute, but don't know where to get started then looking at our currently open issues or unimplemented endpoints would be suggested.

We do not provide a way support us monetarily (at this time). We suggest supporting the wonderful Hydrus Developer on their Patreon instead. This project would have no reason to exist if it wasn't for the over a decade of work that Hydrus Developer has put into their project.

Versioning

HydrusAPI is versioned using [Hydrus API version].[Hydrus version].[HydrusAPI version].

This works well since all our endpoints should match a given Hydrus API/Client version pair.

We suggest matching Hydrus API version and Hydrus version as closely as possible. Mismatched Hydrus versions should be okay, but mismatched Hydrus API versions could cause serious issues.

When using a package manager you should pin the HydrusAPI version. Here is an example using NPM for Hydrus version 638: npm install [email protected].*. When downloading you should download the version that best matches your Hydrus version.

Below is a list of Hydrus versions supported under a given API version. Use this list to construct your version string for version pinning.

• API Version: 80
  • Hydrus versions: 636+
    • API version 80 should be valid as far back as Hydrus version 622, but HydrusAPI only officially supports (and has been tested with) 636 and newer. If you want to use an older client then you will have to use HydrusAPI version 80.636.* with it.

Thanks and Attribution

NPM badge provided by NodeICO.

Hydrus version, reported bugs, issue count, and minified size badges provided by Shields.io.

Code coverage badges provided by Warren Jervis's Vitest Badge Action.

Hummingbird at feeder image (used in testing) provided by Paul Brennan on PublicDomainPictures.net.

Tree image (used in testing) provided by George Hodan on PublicDomainPictures.net.

Tokyo travel image (used in testing) provided by Karen Arnold on PublicDomainPictures.net.

Venice travel image (used in testing) provided by Karen Arnold on PublicDomainPictures.net.

Seascape Sunset image (used in testing) provided by Jean Beaufort on PublicDomainPictures.net.

License

HydrusAPI is licensed under the same DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE as Hydrus is as of August 23rd 2025.

Endpoints

This is all the endpoints that exist as of Hydrus API version 80. Checked endpoints have been implemented or are no longer available.

• /api_version
• /request_new_permissions
  • While this is implemented and we do not expect it to break it cannot be automatically tested due to its nature.
• /session_key
• /verify_access_key
• /get_service
• /get_services
• /add_files/add_file
• /add_files/delete_files
• /add_files/undelete_files
• /add_files/clear_file_deletion_record
• /add_files/migrate_files
• /add_files/archive_files
• /add_files/unarchive_files
• /add_files/generate_hashes
• /add_urls/get_url_files
• /add_urls/get_url_info
• /add_urls/add_url
• /add_urls/associate_url
• /add_tags/clean_tags
• /add_tags/get_tag_services
  • No longer supported.
  • Use /get_services instead.
• /add_tags/get_favourite_tags
• /add_tags/get_siblings_and_parents
• /add_tags/search_tags
• /add_tags/add_tags
• /add_tags/set_favourite_tags
• /edit_ratings/set_rating
• /edit_times/increment_file_viewtime
• /edit_times/set_file_viewtime
• /edit_times/set_time
• /add_notes/set_notes
• /add_notes/delete_notes
• /get_files/search_files
• /get_files/file_hashes
• /get_files/file_metadata
• /get_files/file
• /get_files/thumbnail
• /get_files/file_path
• /get_files/thumbnail_path
• /get_files/local_file_storage_locations
• /get_files/render
• /manage_file_relationships/get_file_relationships
• /manage_file_relationships/get_potentials_count
• /manage_file_relationships/get_potential_pairs
• /manage_file_relationships/get_random_potentials
• /manage_file_relationships/remove_potentials
• /manage_file_relationships/set_file_relationships
• /manage_file_relationships/set_kings
• /manage_services/get_pending_counts
• /manage_services/commit_pending
  • Due to the nature of this endpoint it doesn't have a test.
• /manage_services/forget_pending
  • Due to the nature of this endpoint it doesn't have a test.
• /manage_cookies/get_cookies
• /manage_cookies/set_cookies
• /manage_headers/get_headers
• /manage_headers/set_headers
• /manage_headers/set_user_agent
  • Will NOT BE implemented due to it being deprecated.
  • Use /manage_headers/set_headers instead.
• /manage_pages/get_pages
• /manage_pages/get_page_info
• /manage_pages/add_files
• /manage_pages/focus_page
• /manage_pages/refresh_page
• /manage_popups/get_popups
• /manage_popups/add_popup
• /manage_popups/call_user_callable
• /manage_popups/cancel_popup
• /manage_popups/dismiss_popup
• /manage_popups/finish_popup
• /manage_popups/finish_and_dismiss_popup
• /manage_popups/update_popup
• /manage_database/force_commit
• /manage_database/lock_on
• /manage_database/lock_off
• /manage_database/mr_bones
• /manage_database/get_client_options
  • While this is implemented it will not be documented or tested due to its UNSTABLE nature!
  • Expect the results of this endpoint to change with each Hydrus Client version!