Adding Torrents and Existing Data

Adding Torrents & Existing Data

There are three ways a torrent enters Hydra, and two very different ways it can treat data that already exists on disk. Getting this right is the difference between "instantly seeding" and "re-downloading 40 GB you already have".

The three add paths

Path	Endpoint	Typical caller
Web UI	Add Torrent button	you
Native REST	POST /api/torrents/upload (multipart file, save_path, mode, category)	scripts
qBittorrent shim	POST /api/v2/torrents/add	autobrr, *arr, cross-seed

mode is race or hoard (the qBit shim derives it from the category — see Categories and Routing).

Two ways to handle data already on disk

When you add a torrent whose files are already present (a re-add after a restart, a cross-seed of the same content, or data you moved in by hand), you choose between:

1. Trust it — skip_checking=true (fast)

The qBit-shim add with skip_checking=true puts the torrent straight into seed mode: no hashing, it starts seeding immediately. This is the cross-seed / hardlink path — instant, but it trusts the bytes on disk. If they're wrong, you'll hand out bad pieces (and a private tracker may hardban you). Use it only when you know the data is correct (e.g. you just hardlinked your own verified files).

2. Verify it — recheck (safe)

Add it in download mode (no skip_checking). If Hydra sees data already at the save path, it hash-checks every piece against the torrent and:

• keeps and serves the pieces that verify,
• fetches only what's missing or corrupt,
• flips to seeding if everything checks out.

This is automatic on add when data is present, and you can also trigger it anytime:

• qBit: POST /api/v2/torrents/recheck with hashes=<infohash>
• native: POST /api/hoard/torrents/<infohash>/verify

Recheck is hoard-only. The race engine has no piece picker to record per-piece verification, so verify/recheck on a race torrent returns an explicit error. Recheck what you intend to seed.

hashes=all is intentionally ignored. A mass recheck over a 100k-torrent hoard would be a disk storm. Pass explicit info-hashes.

Which should I use?

• Cross-seeding your own freshly-linked data → skip_checking=true (fast, you trust it).
• Importing data from elsewhere, re-adding after a crash, or unsure → download mode and let the recheck establish what's really valid.

Save-path convention (important for existing data)

Recheck (and normal seeding) can only find your data if the save path matches where the engine looks:

• Single-file torrent → the engine reads save_path/<name>. Pass the parent directory as save_path; the file itself must be at save_path/<name>.
• Multi-file torrent → the engine reads save_path/<name>/<file…>. Pass the directory that contains the torrent's top folder.

If a recheck reports 0/N verified on data you're sure exists, it's almost always a save-path mismatch (the file is one directory level off from where the engine looked). Check the torrent's save_path in get files / the detail panel and line it up.

Boot behaviour

On restart the engine reloads its resume data and the durable store, so it does not re-hash your whole hoard — it trusts resume for what it already had. Recheck is for the add / on-demand case, never a boot-wide scan.