HTTP API

HTTP API and health checks

The web page talks to a JSON API that you can use for scripts as well. It has no authentication either, so the warning in the README applies: do not expose port 8080 to the internet.

Request	Purpose
GET /api/config	Limits, the number of default passwords and the downloads folder.
POST /api/downloads/analyze	Checks a list of links, as the form does while you type.
POST /api/downloads	Starts a download.
GET /api/downloads	Lists all downloads.
GET /api/downloads/{id}	One download with all its episodes and parts.
POST /api/downloads/{id}/pause	Pauses it (/resume resumes it). Episodes that are being unpacked are not paused.
POST /api/downloads/{id}/cancel	Cancels it (/retry starts failed or canceled episodes again).
PUT /api/downloads/{id}/auto-unpack	Body {"unpack": true} or false: whether the episodes that are not downloaded yet are unpacked afterwards. 409 when none of the episodes can be changed any more.
POST /api/downloads/{id}/unpack	Unpacks every episode that waits to be unpacked.
POST /api/downloads/{id}/cancel-unpack	Stops the unpacking of every episode that is being unpacked. They go back to Downloaded.
POST /api/downloads/{id}/password	Sends a password for the waiting episodes.
POST /api/downloads/{id}/items/{n}/pause	Pauses episode n (/resume, /cancel and /retry too).
PUT /api/downloads/{id}/items/{n}/auto-unpack	The same for episode n. 409 once it is downloaded.
POST /api/downloads/{id}/items/{n}/unpack	Unpacks episode n, if it waits to be unpacked.
POST /api/downloads/{id}/items/{n}/cancel-unpack	Stops the unpacking of episode n, if it is being unpacked.
DELETE /api/downloads/{id}/items/{n}	Removes episode n from the download. Files on disk stay.
DELETE /api/downloads/{id}	Removes it from the list. Files on disk stay.
GET /api/downloads/stream	Server-Sent Events: job, notice and removed messages.
GET /health/live	The process answers.
GET /health/ready	The downloads folder is writable and 7-Zip works.
GET /health	All checks.

A download is started like this:

curl -X POST http://localhost:8080/api/downloads -H "Content-Type: application/json" \
  -d '{"name": "Frieren", "kind": "Season", "season": 1, "format": null, "password": null, "links": "https://…\nhttps://…"}'

The body of POST /api/downloads also takes "unpack": false. The default is true. With false, the episodes stop at the stage Downloaded (and the download at the status Downloaded) until unpack is called for them. Every episode in the answers has unpack (what it is set to) and canChangeUnpack (whether auto-unpack would still be accepted). That holds while the episode is fetching links or parts, is paused, has failed or was canceled; a retry then follows the setting. cancel-unpack sets unpack to false, and unpack sets it to true again.

The container calls /health/live itself every 30 seconds, and that is what healthy in docker compose ps means.