Skip to content

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

upPollo serve

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
sudo systemctl enable --now uppollo

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):

{"status": "queued", "message": "Release processing queued"}

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 info and nothing else.
  • info holds exactly files (for a directory, also one with a single file) or length (for a single file), name, piece length, pieces and private with the value 0. Every entry of files holds exactly length and path.
  • name is the base name of the upload path.
  • files lists 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, ._*, __MACOSX or @eaDir, and files whose path ends in .torrent, .ds_store, thumbs.db, desktop.ini or zone.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:

  1. 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.
  2. name and the form (files or length) fit the upload path.
  3. The file list equals, in order and with the sizes, the list upPollo would hash.
  4. The content size and the piece length are the ones mkbrr plans for the tracker, and pieces holds 20 bytes per piece.
  5. No file of the content was modified after the .torrent file was written.
  6. 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 against disk_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/identify always counts as false)
  • every ID the request sends in IMDBID or TMDBID (an IMDb ID with or without tt) to be one the remembered identification has, whichever IDs that one was asked with. So an /api/upload that sends the TMDBID or IMDBID an /api/identify returned still skips identification. A request with other IDs logs Identification 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 (IDSource set). 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 logs Identification 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 in config.yaml against what you send; the body field is APIKey (case-sensitive). Watch for stray whitespace.
  • API port must be set in configuration — set api.port.
  • bind: address already in use — another process uses the port (lsof -i :9999); change api.port or 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. Send Path pointing to a folder that holds only this release instead of InfoHash.
  • Upload queued but nothing happens — check the daily log in logging.directory and verify the path/info hash is valid and readable. logging.level: "debug" shows the full pipeline, including cross-seed webhook calls.