Skip to content

Client API

The hydrus client now supports a very simple API so you can access it with external programs.

Enabling the API

By default, the Client API is not turned on. Go to services->manage services and give it a port to get it started. I recommend you not allow non-local connections (i.e. only requests from the same computer will work) to start with.

The Client API should start immediately. It will only be active while the client is open. To test it is running all correct (and assuming you used the default port of 45869), try loading this:

You should get a welcome page. By default, the Client API is HTTP, which means it is ok for communication on the same computer or across your home network (e.g. your computer's web browser talking to your computer's hydrus), but not secure for transmission across the internet (e.g. your phone to your home computer). You can turn on HTTPS, but due to technical complexities it will give itself a self-signed 'certificate', so the security is good but imperfect, and whatever is talking to it (e.g. your web browser looking at may need to add an exception.

The Client API is still experimental and sometimes not user friendly. If you want to talk to your home computer across the internet, you will need some networking experience. You'll need a static IP or reverse proxy service or dynamic domain solution like so your device can locate it, and potentially port-forwarding on your router to expose the port. If you have a way of hosting a domain and have a signed certificate (e.g. from Let's Encrypt), you can overwrite the client.crt and client.key files in your 'db' directory and HTTPS hydrus should host with those.

Once the API is running, go to its entry in services->review services. Each external program trying to access the API will need its own access key, which is the familiar 64-character hexadecimal used in many places in hydrus. You can enter the details manually from the review services panel and then copy/paste the key to your external program, or the program may have the ability to request its own access while a mini-dialog launched from the review services panel waits to catch the request.

Tools created by hydrus users

Browser Add-on

  • Hydrus Companion: a Chrome/Firefox extension for hydrus that allows easy download queueing as you browse and advanced login support

Client Browsing

  • Hydrus Web: a web client for hydrus (allows phone browsing of hydrus)
  • Hyshare: a way to share small galleries with friends--a replacement for the old 'local booru' system
  • Hydra Vista: a macOS client for hydrus
  • LoliSnatcher: a booru client for Android that can talk to hydrus
  • Anime Boxes: a booru browser, now supports adding your client as a Hydrus Server
  • FlipFlip: an advanced slideshow interface, now supports hydrus as a source
  • Hydrus Archive Delete: Archive/Delete filter in your web browser

Advanced Downloading

  • hydownloader: Hydrus-like download system based on gallery-dl