client api

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

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.

Browsers and tools created by hydrus users:

Library modules created by hydrus users:


In general, the API deals with standard UTF-8 JSON. POST requests and 200 OK responses are generally going to be a JSON 'Object' with variable names as keys and values obviously as values. There are examples throughout this document. For GET requests, everything is in standard GET parameters, but some variables are complicated and will need to be JSON encoded and then URL encoded. An example would be the 'tags' parameter on GET /get_files/search_files, which is a list of strings. Since GET http URLs have limits on what characters are allowed, but hydrus tags can have all sorts of characters, you'll be doing this:

On 200 OK, the API returns JSON for everything except actual file/thumbnail requests. On 4XX and 5XX, assume it will return plain text, which may be a raw traceback that I'd be interested in seeing. You'll typically get 400 for a missing parameter, 401/403/419 for missing/insufficient/expired access, and 500 for a real deal serverside error.

Access and permissions

The client gives access to its API through different 'access keys', which are the typical 64-character hex used in many other places across hydrus. Each guarantees different permissions such as handling files or tags. Most of the time, a user will provide full access, but do not assume this. If the access header or parameter is not provided, you will get 401, and all insufficient permission problems will return 403 with appropriate error text.

Access is required for every request. You can provide this as an http header, like so:

Or you can include it as a GET or POST parameter on any request (except POST /add_files/add_file, which uses the entire POST body for the file's bytes). Use the same name for your GET or POST argument, such as:

There is now a simple 'session' system, where you can get a temporary key that gives the same access without having to include the permanent access key in every request. You can fetch a session key with the /session_key command and thereafter use it just as you would an access key, just with Hydrus-Client-API-Session-Key instead.

Session keys will expire if they are not used within 24 hours, or if the client is restarted, or if the underlying access key is deleted. An invalid/expired session key will give a 419 result with an appropriate error text.

Bear in mind the Client API is still under construction. Setting up the Client API to be accessible across the internet requires technical experience to be convenient. HTTPS is available for encrypted comms, but the default certificate is self-signed (which basically means an eavesdropper can't see through it, but your ISP/government could if they decided to target you). If you have your own domain and SSL cert, you can replace them though (check the db directory for client.crt and client.key). Otherwise, be careful about transmitting sensitive content outside of your localhost/network.


Access Management

GET /api_version

Gets the current API version. I will increment this every time I alter the API.

GET /request_new_permissions

Register a new external program with the client. This requires the 'add from api request' mini-dialog under services->review services to be open, otherwise it will 403.

GET /session_key

Get a new session key.

GET /verify_access_key

Check your access key is valid.

GET /get_services

Ask the client about its file and tag services.

Adding Files

POST /add_files/add_file

Tell the client to import a file.

POST /add_files/delete_files

Tell the client to send files to the trash.

POST /add_files/undelete_files

Tell the client to pull files back out of the trash.

POST /add_files/archive_files

Tell the client to archive inboxed files.

POST /add_files/unarchive_files

Tell the client re-inbox archived files.

Adding Tags

GET /add_tags/clean_tags

Ask the client about how it will see certain tags.

GET /add_tags/get_tag_services

This is now legacy! Use /get_services instead!

Ask the client about its tag services.

POST /add_tags/add_tags

Make changes to the tags that files have.

Adding URLs

GET /add_urls/get_url_files

Ask the client about an URL's files.

GET /add_urls/get_url_info

Ask the client for information about a URL.

POST /add_urls/add_url

Tell the client to 'import' a URL. This triggers the exact same routine as drag-and-dropping a text URL onto the main client window.

POST /add_urls/associate_url

Manage which URLs the client considers to be associated with which files.

Managing Cookies and HTTP Headers

This refers to the cookies held in the client's session manager, which are sent with network requests to different domains.

GET /manage_cookies/get_cookies

Get the cookies for a particular domain.

POST /manage_cookies/set_cookies

Set some new cookies for the client. This makes it easier to 'copy' a login from a web browser or similar to hydrus if hydrus's login system can't handle the site yet.

POST /manage_headers/set_user_agent

This sets the 'Global' User-Agent for the client, as typically editable under network->data->manage http headers, for instance if you want hydrus to appear as a specific browser associated with some cookies.

Managing Pages

This refers to the pages of the main client UI.

GET /manage_pages/get_pages

Get the page structure of the current UI session.

GET /manage_pages/get_page_info

Get information about a specific page.

This is under construction. The current call dumps a ton of info for different downloader pages. Please experiment in IRL situations and give feedback for now! I will flesh out this help with more enumeration info and examples as this gets nailed down. POST commands to alter pages (adding, removing, highlighting), will come later.

POST /manage_pages/add_files

Add files to a page.

POST /manage_pages/focus_page

'Show' a page in the main GUI, making it the current page in view. If it is already the current page, no change is made.

Searching Files

File search in hydrus is not paginated like a booru--all searches return all results in one go. In order to keep this fast, search is split into two steps--fetching file identifiers with a search, and then fetching file metadata in batches. You may have noticed that the client itself performs searches like this--thinking a bit about a search and then bundling results in batches of 256 files before eventually throwing all the thumbnails on screen.

GET /get_files/search_files

Search for the client's files.

GET /get_files/file_metadata

Get metadata about files in the client.

GET /get_files/file

Get a file.

GET /get_files/thumbnail

Get a file's thumbnail.

Managing the Database

POST /manage_database/lock_on

Pause the client's database activity and disconnect the current connection.

POST /manage_database/lock_off

Reconnect the client's database and resume activity.