This project has been archived. I have stopped using Hydrus in my day to day life and cannot justify the time required to upkeep this project. Feel free to fork this and make your own changes.
-blue){kind=icon}
HydrusAPI is an implementation of the Hydrus Network API in JavaScript. The goal is to fully support the most recent version of the Hydrus Network 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 Network 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.
If you are using npm (or an alternative) package manager then installation is as simple as npm install hydrusapi@81.643.*.
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.
For other users you can download from the releases page.
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.
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.
HydrusAPI is versioned using [Hydrus Network API version].[Hydrus Network client version].[HydrusAPI version].
This works well since all our endpoints should match a given Hydrus Network API/Client version pair.
We suggest matching Hydrus Network API version and Hydrus Network client version as closely as possible. Mismatched Hydrus Network client versions should be okay, but mismatched Hydrus Network 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 643: npm install hydrusapi@81.643.*. When downloading you should download the version that best matches your Hydrus Network 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 to 639
- 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.639.* with it.
- Hydrus versions: 636 to 639
- API Version: 81
- Hydrus versions 640+
NPM badge provided by NodeICO.
Hydrus Network API 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.
HydrusAPI is licensed under the same DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE as Hydrus Network is as of August 23rd 2025.
This is all the endpoints that exist as of Hydrus Network API version 81. 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_servicesinstead.
-
/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- This will NOT BE implemented due to it being deprecated.
- Use
/manage_headers/set_headersinstead.
-
/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 endpoint's response will be type defined it will not be documented or tested due to its UNSTABLE nature!
- Expect the results of this endpoint TO CHANGE between different Hydrus Network client versions!