API mode¶
upPollo serve runs an HTTP API server so uploads can be triggered programmatically —
from torrent client hooks, cross-seed, or your own scripts. Requests are queued and
processed in the background, one at a time by default (see Throughput).
API mode is only available for RocketHD and restricted to certain RocketHD user groups; the server checks your account's group with RocketHD (see Authentication). AnimeWorld uploads are rejected in API mode — use the CLI instead (
upPollo upload --tracker aw ...).
Configuration¶
api:
port: 9999 # required
api_key: "" # auto-generated on first run
require_api_key: true # set to false to disable authentication
upload_workers: 1 # queued uploads processed in parallel, see Throughput
disk_concurrency: 0 # reads of whole files at the same time, 0 = no limit, see Throughput
identify_cache_minutes: 15 # reuse identifications this long, 0 = off, see Reused identifications
cross_seed: # optional, see below
enabled: false
url: "http://localhost:2468"
api_key: ""
Logs go to daily files (YYYY-MM-DD.log) in logging.directory, like in CLI mode.
For automatic updates in API mode (checked at auto_update.schedule, applied once all
active uploads and queued CrowdNFO submissions finish), see
Getting started: Automatic updates.
Authentication¶
Every request must carry the API key in the request body — as the APIKey field of
the JSON payload, or as a form field for URL-encoded requests. On first server start
(or on config migrate), a random 32-character key is generated into api.api_key if
none is set; you can also set your own.
curl -X POST http://localhost:9999/api/upload \
-H "Content-Type: application/json" \
-d '{"APIKey": "your-api-key", "Path": "/downloads/Movie.Title.2023"}'
A missing or wrong key returns 401 {"error": "Invalid or missing API key"}.
To rotate the key, clear api.api_key, run upPollo config migrate, and a new one is
generated. To disable authentication entirely, set require_api_key: false — only do
this on trusted networks, since anyone who can reach the port can then trigger
uploads.
Every request is also checked against the user group of the RocketHD account in your
config. The server remembers a permitted group for 10 minutes and asks RocketHD again
on the first request after that, so a group change on RocketHD reaches a running
server after at most 10 minutes. A denied group or a failed check is not remembered:
the next request asks again, and a promotion applies at once. Requests that arrive
while RocketHD is being asked wait for that answer instead of asking themselves. If
RocketHD cannot be reached, the tracker client retries for up to two and a half
minutes before the request fails with 500 {"error": "Failed to verify user group
with tracker"}.
Running the server¶
For production, run it as a systemd service:
# /etc/systemd/system/uppollo.service
[Unit]
Description=upPollo API Server
After=network.target
[Service]
Type=simple
User=your-username
WorkingDirectory=/home/your-username
ExecStart=/usr/local/bin/upPollo serve
Restart=on-failure
RestartSec=10
[Install]
WantedBy=multi-user.target
In Docker, the container runs serve by default — see Docker.
Endpoints¶
POST /api/upload¶
Queues an upload. Responds immediately; processing happens in the background.
| Field | Type | Description |
|---|---|---|
APIKey |
string | Required unless authentication is disabled |
Path |
string | Path to the release's file or directory (this or InfoHash is required). . and .. are resolved first, a path that ends up at ., .. or a file system root is rejected |
InfoHash |
string | Torrent info hash as an alternative to Path. upPollo asks the torrent client where the torrent lives and uploads its top-level folder, or the file itself for a torrent without folder |
IMDBID |
string | IMDb ID, e.g. "tt1234567". Unlike an ID upPollo finds itself, it is not checked against the release name (see How a release is identified) |
TMDBID |
int | TMDb ID (integer, not a string), not checked against the release name either |
ForceTvShow |
bool | Force the TV category (like --force-tv) |
AllowSD |
bool | Allow SD for this upload after verifying that no HD release exists (default: false) |
Anon |
bool | Anonymous upload |
Pr |
bool | Flag as personal release |
Internal |
bool | Flag as internal (RocketHD, only if the account may upload internal) |
ModQ |
bool | Opt in to the moderation queue |
CRC |
bool | Verify CRC32 against SRRDB (scene releases) |
SkipSRRDB |
bool | Skip SRRDB scene detection, NFO renaming and scene verification. Only for unmodified scene releases that bring their own NFO, e.g. fetched straight from the site; an NFO is still fetched if none is found locally |
TrumpID |
int | Trump an existing RocketHD torrent by ID |
SkipNameEnrichment |
bool | Skip name enrichment |
SkipIdentifyCache |
bool | Identify anew instead of reusing a recent identification (see Reused identifications) |
Category |
string | Torrent client category/label (replaces the deprecated QBC) |
Tags |
[]string | Torrent client tags (replaces the deprecated QBT) |
QBCheckHash |
bool | Force a hash check when adding the torrent |
AutoTMM |
bool | Enable automatic torrent management (qBittorrent) |
UploadDelay |
int | Minimum seconds between a torrent's upload and adding it to the client. With a delay, a torrent goes to the client at the first upload after its delay has passed, or at the end of the run |
KeepTemp |
bool | Preserve the temporary upload directory after completion or failure |
Tracker |
string | Target tracker (only "rhd" is allowed in API mode) |
Trackers |
[]string | Multi-tracker form; takes precedence over Tracker |
Torrent |
string | Absolute path of a .torrent file the caller has hashed for the content at Path. If it passes the checks, upPollo uses it instead of hashing the content, see Supplied torrents |
API uploads always run unattended, and filters and dupe checks cannot be bypassed
(the CLI's --ignore-filters / --ignore-dupe have no API equivalent).
SD uploads (480p/i, 540p, 576p/i, including DVD releases) are blocked unless the
request explicitly sets "AllowSD": true. SD is only allowed when no HD release
exists; verify this manually before setting the field. upPollo does not check HD
availability automatically. The permission applies only to that request and can
also be sent as the URL-encoded form field AllowSD=true.
curl -X POST http://localhost:9999/api/upload \
-H "Content-Type: application/json" \
-d '{"APIKey": "your-api-key", "Path": "/downloads/Movie.2024.German.576p.DVDRip.x264-GROUP", "AllowSD": true}'
Success response (200):
Errors: 400 for a missing Path/InfoHash, malformed JSON, or Tracker: "aw";
401 for a bad API key; 405 for anything but POST. A common 400 cause is passing
TMDBID as a string — it must be an integer.
POST /api/upload/check¶
Runs the validation pipeline — identification, filters, dupe check — without
uploading; the HTTP equivalent of upload --dry-run. Accepts the same fields as
/api/upload. Useful for pre-flight checks and for extracting release metadata
programmatically.
The same SD restriction applies here: without AllowSD: true, an SD release
returns result.valid: false with the reason in result.filter_reason.
Response (200, even when validation fails — check result.valid):
{
"result": {
"valid": true,
"release_name": "Movie.Title.2024.1080p.WEB-DL.DDP5.1.H.264-GROUP",
"enriched_name": "Movie Title 2024 1080p WEB-DL DDP5.1 H.264-GROUP",
"release_metadata": {
"TitleDE": "Deutscher Titel",
"TitleEN": "English Title",
"ImdbID": "tt1234567",
"TmdbID": 98765,
"Year": 2024
},
"filter_passed": true,
"dupe_passed": true,
"season": -1,
"episode": -1,
"resolution_id": 3,
"category_id": 1,
"type_id": 5
},
"messages": [
{"type": "success", "message": "Identified Release: 'English Title' (2024)"}
]
}
For full-disc series releases, result.disc holds the disc number extracted from
the name (e.g. S01D02 → 2); it's omitted when the release has no disc marker.
For a full disc, trackers without seed_on_dupe are asked for an upload of exactly
the same size before the disc scan (see
Full disc uploads). A dupe
found there is reported with dupe_passed: false, and with filter_passed: true and
filter_reason: "skipped (dupe found before the disc scan)", because the filters
that read the disc did not run. When this leaves no tracker, the disc is not scanned:
enriched_name is missing, resolution_id comes from the release name (10, Other,
when the name has none), and the top-level filter_passed is true as well, since
it repeats the first tracker's result.
With seed_on_dupe, a dupe whose .torrent matches your files passes the check:
/api/upload would seed it instead of uploading. dupe_passed is true and
dupe_reason starts with seed_on_dupe: (see
Seed on dupe).
On failure, filter_reason / dupe_reason / error_message explain why. When
checking multiple trackers, result.tracker_results holds the per-tracker outcome
(tracker, filter_passed, filter_reason, dupe_passed, dupe_reason,
error_message). A 500 with an error field means identification itself failed.
A 409 with an error field means an upload or another check of the same release is
running. The check does not wait for it, since an upload can take longer than the
request may; retry once it has finished. An upload that arrives during a check waits
for the check. A 503 with error and hint means the check gave up waiting for
other uploads to finish reading from disk (see disk_concurrency under
Throughput); retry it later.
POST /api/identify¶
Identifies a release by name only — no files needed. Returns the same metadata object as the check endpoint.
| Field | Type | Description |
|---|---|---|
APIKey |
string | Required unless authentication is disabled |
ReleaseName |
string | Required — the release name to identify |
NfoContent |
string | Optional NFO text to aid identification |
IMDBID |
string | Optional known IMDb ID |
TMDBID |
int | Optional known TMDb ID |
SkipIdentifyCache |
bool | Identify anew instead of reusing a recent identification (see Reused identifications) |
Response (200): {"metadata": {...}, "messages": [...], "features": ["torrent", "upload-first"]}.
When the release was identified by an ID upPollo found itself (from NfoContent, on
XREL, SRRDB or CrowdNFO), metadata.IDSource names the source and
metadata.TitleScore rates from 0 to 100 how well the title in the release name
matches that film or show. Below 50, /api/upload and /api/upload/check stop at
this identification, and messages holds the same warning already (see
How a release is identified). For an ID given in
IMDBID or TMDBID, or a title search result, IDSource is empty.
features lists what the server supports beyond the fields above, so a client can
decide per release what to send. A server that does not send the list supports none
of them.
| Value | Meaning |
|---|---|
torrent |
/api/upload accepts the Torrent field, see Supplied torrents |
upload-first |
The RocketHD upload does not wait for the screenshots: it goes out as soon as the torrent is ready, and the screenshots are added to the description afterwards (see Throughput). A supplied torrent therefore shortens the upload of every release, whatever its size. A client that does not see the value leaves out the torrent for content it expects to be hashed while the screenshots are taken |
Supplied torrents¶
A caller that has already read the content, for example a downloader that hashes
while it downloads, can hand over its piece hashes: Torrent in /api/upload is the
absolute path of a .torrent file for the content at Path. upPollo sets the
tracker's announce URL and source on a copy of it and does not hash the content. The
server reads the file under the path given, so in Docker the directory has to be
mounted under the same path as on the caller's side. upPollo never changes or deletes
the file.
The file has to hold what upPollo's own hashing writes for the content before tracker and source are set:
- A v1 torrent whose root dictionary holds
infoand nothing else. infoholds exactlyfiles(for a directory, also one with a single file) orlength(for a single file),name,piece length,piecesandprivatewith the value0. Every entry offilesholds exactlylengthandpath.nameis the base name of the upload path.fileslists every file below the directory, hidden and empty ones included, ordered by the path joined with/, byte by byte. Left out are paths with a directory or file name that matches, ignoring case, one of*.webp,*.jpg,*.jpeg,*.png,*.srs,*.srr,*.sfv,*.rar,*.r[0-9][0-9],*.r[0-9][0-9][0-9],*.metathumb,*sample*,*.xml,*.mp3,*.flac,*.wav,*.aac,*.m4a,*.ogg,*.wma,*.par2,.DS_Store,._*,__MACOSXor@eaDir, and files whose path ends in.torrent,.ds_store,thumbs.db,desktop.iniorzone.identifier.- The piece length follows the size of the listed files: 32 KiB up to 64 MiB, 64 KiB up to 128 MiB, and so on doubling with the size up to 8 MiB for 16 GiB; anything larger gets 16 MiB.
upPollo checks the file in this order and stops at the first failure:
- The path is absolute and names a regular file of at most 8 MiB that decodes as described above. The piece hashes of 1 TiB of content in 16 MiB pieces take 1.3 MiB.
nameand the form (filesorlength) fit the upload path.- The file list equals, in order and with the sizes, the list upPollo would hash.
- The content size and the piece length are the ones mkbrr plans for the tracker,
and
piecesholds 20 bytes per piece. - No file of the content was modified after the
.torrentfile was written. - A spot check hashes every piece that holds bytes of more than one file, and the
first and the last piece inside each file, and compares them with
pieces. It reads and hashes up to four pieces at the same time. A check that reads more than 4 GiB counts againstdisk_concurrency(see Throughput).
A failed check never fails the upload: the log gets the warning Supplied torrent not
used: <reason>, and the content is hashed as if the field had not been sent. That
also happens when upPollo itself changed the content before hashing, for example when
it adds or replaces an NFO, stages the release as a copy, or renames files of a scene
release. Content that holds links to directories, broken links or files with names in
decomposed Unicode form is never compared with a supplied torrent and always hashed.
On success the log says Using the supplied torrent (skipped hashing).
The spot check is the only part that reads the content. Pieces in the middle of a file are not read, so a wrong hash there goes unnoticed: the torrent is uploaded, and that piece never completes for anyone. The caller is responsible for the hashes it supplies and should verify its torrent against the content itself.
Full discs are always hashed by upPollo, since their torrent leaves out other files. With several trackers the supplied torrent stands in for the one hashing: trackers without piece size rules get a copy of it, a tracker whose rules ask for another piece length fails check 4 and gets its own hashed torrent.
Reused identifications¶
The server remembers each successful identification for api.identify_cache_minutes
(15 by default), whichever endpoint ran it. Set it to 0 to identify every request
anew. A later /api/identify, /api/upload/check or /api/upload for the same
release reuses it instead of asking XREL, SRRDB, CrowdNFO, TMDb and TVDb again, and
logs Using identification from … ago. So an upload right after an identify or a
check of the same release skips identification. A reuse needs:
- the same release name, ignoring upper and lower case. For uploads, that is the name upPollo works with after the media server lookup and scene verification
- the same
ForceTvShow(/api/identifyalways counts asfalse) - every ID the request sends in
IMDBIDorTMDBID(an IMDb ID with or withouttt) to be one the remembered identification has, whichever IDs that one was asked with. So an/api/uploadthat sends theTMDBIDorIMDBIDan/api/identifyreturned still skips identification. A request with other IDs logsIdentification from … ago has other IDs than requested, identifying again, identifies anew, and its result replaces the remembered one - for a request without IDs, an identification from an ID upPollo found itself
(
IDSourceset). One made from IDs another request sent is not reused, since those IDs are not checked against the release name and this request's NFO or Matroska tags may name another ID: the request logsIdentification from … ago was made from IDs another request gave, identifying again, and its result replaces the remembered one
The NFO and the media file's Matroska tags are not compared: /api/identify gets
the NFO as NfoContent but never sees the media file. Only identifications from an
IMDb or TMDb ID are remembered, whether the ID came from the request, the NFO, the
Matroska tags, XREL, SRRDB or CrowdNFO, so a request with other files can't get a
worse result than its own lookup. These are not remembered:
- guesses from the title search on TMDb, since a later request's NFO or Matroska tags may name the right ID
- identifications by a found ID whose film or show does not match the release name (see How a release is identified), for the same reason
- incomplete identifications: a show whose TVDb ID could not be looked up, or whose season TVDb or TMDb could not answer for (with or without an error)
- failed identifications and results without a title
Changes on TMDb or TVDb within that time, such as a newly aired finale that
affects the grace period or a title fixed on TMDb, are only seen once they are over. To get them
sooner, set "SkipIdentifyCache": true on /api/identify, /api/upload/check or
/api/upload: that request identifies anew and its result replaces the remembered
one. A restart of the server clears the cache, and the CLI never uses it.
Cross-seed integration¶
With api.cross_seed.enabled: true, upPollo calls your
cross-seed instance's webhook at the start of each
queued upload that names an InfoHash, so cross-seed searches its indexers for the
release and can inject matches into your client:
POST {url}/api/webhook
X-Api-Key: {api_key}
Content-Type: application/x-www-form-urlencoded
infoHash={torrent_info_hash}
Uploads that only name a Path skip the call. It runs beside the upload, so a slow
or unreachable cross-seed does not delay it. upPollo tries up to three times with a
30-second timeout each and writes the outcome to the upload's log before the upload
finishes. The job only ends once cross-seed has answered, so with upload_workers: 1
a cross-seed that does not respond holds the next queued upload for up to about 93
seconds whenever the upload itself ends sooner, for example after a filter or dupe
rejection.
Automation examples¶
qBittorrent (Settings → Downloads → Run external program on torrent completion), using
the %I info-hash placeholder:
curl -X POST http://localhost:9999/api/upload --data-urlencode "APIKey=your-api-key" --data-urlencode "InfoHash=%I" --data-urlencode "Category=uppollo"
Pre-flight check, then extract metadata with jq:
curl -s -X POST http://localhost:9999/api/upload/check \
-H "Content-Type: application/json" \
-d '{"APIKey": "your-api-key", "Path": "/downloads/Movie.Title.2023"}' \
| jq '.result.release_metadata'
Throughput¶
In API mode the torrent is hashed while the screenshots are generated and uploaded, instead of afterwards; nothing has to be configured for that. The CLI keeps both steps apart so their progress bars stay readable. With several trackers in one request the content is hashed once; the other trackers get a copy of that torrent with their own announce URL and source.
upload_workers sets how many queued uploads run at the same time. The default 1
processes the queue one by one. Raise it to 2 if releases often arrive together, for
example several episodes at once, and the machine has fast storage (SSD/NVMe) and spare
CPU. On HDDs and NAS storage, uploads that hash at the same time compete for the disk
and each one gets slower: there, combine upload_workers: 2 or 3 with
disk_concurrency: 1 (see below), or keep 1. Each upload also runs its own
screenshot ffmpeg processes, and a 2160p HDR screenshot takes up to about 1 GB of
memory per process; with the default num: 4, that is up to about 5 GB per upload
(see Configuration: Screenshots). Requests for the same
release never run in parallel, the second upload waits for the first. That includes
requests that name it differently: by path or by info hash, with or without a trailing
slash, or a folder of the same name in another directory, since they share the temp
directory. Checks run beside the queue even with one worker, so a
check of a release that is being uploaded answers 409 right
away instead of waiting.
disk_concurrency caps how many reads of whole release files run at the same time
across all uploads: torrent hashing, CRC32 verification (CRC), Blu-ray disc scans,
extracting the main title of a DVD image, CrowdNFO submissions, and copies of files of
8 MiB or more (link_mode: copy, or a hardlink across file systems that falls back to
a copy). The default 0 sets no limit. With 1, one upload reads from disk while the
others identify their release, take and upload screenshots or talk to the tracker, so
more than one upload worker pays off on HDDs and NAS storage as well. A hash, CRC32
check, disc scan or CrowdNFO submission that has to wait logs Waiting for another
upload to finish reading from disk; a waiting copy shows up only with
logging.level: "debug". Checks count against the limit too: a check of a full disc
waits for running reads until 10 minutes after the request arrived, then answers
503. Screenshots and MediaInfo read only parts of a file and are not limited, except
the MediaInfo run of a CrowdNFO submission: its slot covers the whole submission,
including its requests to CrowdNFO. The spot check of a
supplied torrent reads up to three pieces per file and is not
limited either, as long as that adds up to at most 4 GiB. A larger check, for example
of a season pack above 16 GiB with more than about 85 episodes, waits for running
reads like a hash.
With CrowdNFO enabled, the submission runs after the upload has finished: it reads the whole media file once more for its hash and runs MediaInfo again, which takes minutes for a large release on an HDD. The torrent is already seeding by then, and the next queued upload starts while the submission runs. Submissions run one at a time, in the order their uploads finished, and the log names the release each one belongs to. They are queued in memory only: an automatic update waits for them like for running uploads, any other restart of the server drops them.
The server logs in to TVDb once and reuses the token for a day across all requests,
instead of logging in for every lookup. For small releases the screenshots usually take
longer than hashing the torrent. RocketHD does not wait for them: the torrent is
uploaded once it is hashed, and the screenshots are added to its description when they
are hosted (see Configuration: Screenshots). On
AnimeWorld their upload still decides when the tracker upload can start.
screenshots.parallel_uploads uploads them at the same time, which shortens the wait on
AnimeWorld and the time a RocketHD torrent shows no screenshots.
Once its RocketHD upload is done, the worker takes the next queued upload. Screenshots
still being taken or hosted finish in the background, and their outcome goes to the
log, not into the response. At most upload_workers uploads run ffmpeg for screenshots
at the same time; a further one logs Waiting for another upload to finish taking its
screenshots. Hosting the images does not count against that limit. An AnimeWorld
upload and a DVD image (ISO/IMG) keep their worker until their screenshots are hosted:
AnimeWorld needs them before the upload, and for a DVD image ffmpeg reads the title
extracted into the upload's temp directory. Both can wait for a slot behind the
screenshots of earlier RocketHD uploads. An upload that fails gives up screenshots that
have not started yet. The log names every torrent whose screenshots follow in the
background. An automatic update waits for them like for CrowdNFO submissions; any
other restart of the server drops them, and those torrents stay without screenshots.
Season packs look up their episodes on SRRDB and download the episode NFOs four at a
time. Across all uploads at most four SRRDB requests run at once, so a higher
upload_workers does not put more load on SRRDB.
Troubleshooting¶
Invalid or missing API key— compare the key inconfig.yamlagainst what you send; the body field isAPIKey(case-sensitive). Watch for stray whitespace.API port must be set in configuration— setapi.port.bind: address already in use— another process uses the port (lsof -i :9999); changeapi.portor stop it.Your Usergroup or Username is not allowed to use the API— API access is limited to specific RocketHD user groups; contact RocketHD staff via the Helpdesk if you believe you should have access.the torrent has no top-level folder in qBittorrent— the torrent has several files and was added with the content layout "Don't create subfolder", so its files sit directly in the save path, possibly next to other downloads. SendPathpointing to a folder that holds only this release instead ofInfoHash.- Upload queued but nothing happens — check the daily log in
logging.directoryand verify the path/info hash is valid and readable.logging.level: "debug"shows the full pipeline, including cross-seed webhook calls.