Downloads - Lionz IPTV Downloader

The Downloads API manages server-side media downloads through Aria2, including status tracking, download control, and user permissions.

List Downloads

Display a paginated list of media downloads for the current user (or all users if admin).

GET /downloads

Route Name: downloads Middleware: auth, verified Controller: MediaDownloadsController::index (app/Http/Controllers/MediaDownloadsController.php:30)

Query Parameters

owners

string

Filter downloads by owner user IDs (admin only)

Comma-separated list of user IDs
Example: "1,3,5"
Ignored for non-admin users
Invalid IDs are filtered out

Response

Returns Inertia response rendering downloads component. Props:

downloads

object

Paginated collection of download references

10 items per page
Ordered by created_at DESC
Includes related media information
For admins: includes owner details (id, name, email)
Merged with live Aria2 download status

ownerOptions

array

Available owner filter options (admin only)

Array of user objects with id, name, email
Only includes users who have downloads

Download Status Fields

Each download includes real-time status from Aria2:

gid - Aria2 download identifier
status - Download status (active, waiting, paused, error, complete, removed)
totalLength - Total file size in bytes
completedLength - Downloaded bytes
downloadSpeed - Current download speed (bytes/sec)
errorCode - Error code if failed
errorMessage - Error description if failed
dir - Download destination directory
files - Array of file information

User Filtering

Members: Only see their own downloads

->where('user_id', $user->id)

Admins: See all downloads, optionally filtered by owner

->when($isAdmin && $ownerIds !== [], fn($query) => $query->whereIn('user_id', $ownerIds))

Controller Reference: MediaDownloadsController.php:36-43

Example

# Get own downloads (member)
GET /downloads

# Get all downloads (admin)
GET /downloads

# Filter by owners (admin)
GET /downloads?owners=1,3,5

Edit Download

Perform an action on a download (pause, resume, retry, cancel, remove).

PATCH /downloads/{model}

Route Name: downloads.edit Middleware: auth, verified, can:download-operations,model Controller: MediaDownloadsController::edit (app/Http/Controllers/MediaDownloadsController.php:79)

Path Parameters

model

integer

required

Download reference ID

Must be numeric
User must have permission to modify this download

Request Body

action

string

required

Action to perform on the download

pause - Pause active download
resume - Resume paused download
retry - Retry failed download
cancel - Cancel download and optionally delete partial file
remove - Remove download from list
Validated via MediaDownloadAction enum

delete_partial

boolean

Whether to delete partial file when canceling

Only applies when action is cancel
Default: false

restart_from_zero

boolean

Whether to restart download from beginning when retrying

Only applies when action is retry
Default: false

Response

Returns redirect back to previous page. Success Messages:

“Download canceled successfully.”
“Download retried successfully.”
“Download status updated successfully.”

Error Messages:

“This download is already canceled and cannot be modified.”
“Retry is temporarily unavailable while this download is cooling down.”
“You cannot a download in status.”
“Unsupported download action.”
Aria2 error messages

Action Validation

Actions are validated against current download status:

$allowed = $data->status->canTakeAction($payload->action);

Status-Action Compatibility:

Active downloads: can pause, cancel
Paused downloads: can resume, cancel
Error/Complete downloads: can retry, remove
Waiting downloads: can cancel

Controller Reference: MediaDownloadsController.php:117-128

Special Behaviors

Cancel Action:

Stops Aria2 download
Optionally deletes partial file
Marks download as canceled in database
Sets canceled_at timestamp

Retry Action:

Checks retry cooldown period
Removes old Aria2 task
Creates new download with same parameters
Updates database record with new GID
Can optionally restart from zero

Pause/Resume Actions:

Sends command to Aria2
Updates desired_paused flag in database
Maintains user’s pause preference

Remove Action:

Removes result from Aria2
Deletes MediaDownloadRef record

Controller Reference: MediaDownloadsController.php:85-153

Example

# Pause download
PATCH /downloads/123
Content-Type: application/json

{"action": "pause"}

# Cancel and delete partial
PATCH /downloads/123
Content-Type: application/json

{"action": "cancel", "delete_partial": true}

# Retry from beginning
PATCH /downloads/123
Content-Type: application/json

{"action": "retry", "restart_from_zero": true}

Delete Download

Cancel a download (shorthand for PATCH with cancel action).

DELETE /downloads/{model}

Route Name: downloads.destroy Middleware: auth, verified, can:download-operations,model Controller: MediaDownloadsController::destroy (app/Http/Controllers/MediaDownloadsController.php:156)

Path Parameters

model

integer

required

Download reference ID

Must be numeric
User must have permission to modify this download

Response

Returns redirect back to previous page. Success:

->with('success', 'Download canceled successfully.')

Errors:

Aria2 error messages if cancellation fails

Behavior

This endpoint is a convenience wrapper that:

Calls CancelDownload::run($model, false)
Does NOT delete partial file
Cancels the Aria2 download
Marks download as canceled

Controller Reference: MediaDownloadsController.php:156-165

Example

DELETE /downloads/123

Download Permissions

The can:download-operations,model middleware enforces ownership:

Permission Logic

Members:

Can only modify their own downloads
Checked via user_id matching

Admins:

Can modify any user’s downloads
No ownership restriction

Database Policy

Permissions are enforced through Laravel’s authorization gates, checking:

$user->id === $download->user_id || $user->role === UserRole::Admin

MediaDownloadRef Model

Downloads are stored in the MediaDownloadRef model: Key Fields:

id - Primary key
gid - Aria2 download GID (unique)
user_id - Owner user ID
downloadable_type - Media type (VodStream or Series)
downloadable_id - Media ID (stream_id or series_id)
episode_id - Episode ID (for series only)
canceled_at - Cancellation timestamp
retry_next_at - Earliest retry time (cooldown)
desired_paused - User’s pause preference
created_at - When download was created

Relationships:

owner - User who initiated download
media - Polymorphic relation to VodStream or Series

Factory Methods:

MediaDownloadRef::fromVodStream($gid, $model, $user)
MediaDownloadRef::fromSeriesAndEpisode($gid, $model, $episode, $user)

Controller Reference: VodStreamDownloadController.php:45, SeriesDownloadController.php:59, 108

Aria2 Integration

Downloads are managed through Aria2 JSON-RPC API:

Status Retrieval

GetDownloadStatus::run(
    $gids,
    ['gid', 'status', 'totalLength', 'completedLength', 'downloadSpeed', 'errorCode', 'errorMessage', 'dir', 'files']
)

Controller Reference: MediaDownloadsController.php:48-51

Download Operations

Pause:

$connector->send(new PauseRequest($gid))

Resume:

$connector->send(new UnPauseRequest($gid))

Remove Result:

$connector->send(new RemoveDownloadResultRequest($gid))

Controller Reference: MediaDownloadsController.php:123-127

Error Handling

Aria2 errors are caught and returned to user:

if ($response->hasError()) {
    return back()->withErrors(['action' => $response->errorMessage()]);
}

Common Errors:

GID not found
Invalid status transition
Network/connection issues
Disk space issues

Download Actions

Actions are defined in the MediaDownloadAction enum:

Available Actions

Controller Reference: EditMediaDownloadData.php:7-18

Download Creation Flow

Downloads are initiated from movie or series endpoints:

Movie Download

User accesses GET /movies/{id}/download
System fetches movie info from Xtream Codes
Checks for existing active downloads
Creates Xtream Codes download URL
Initiates Aria2 download with generated filename
Creates MediaDownloadRef record
Redirects to downloads page

Controller: VodStreamDownloadController.php:28-51

Series Episode Download

User accesses GET /series/{id}/{season}/{episode}/download
System fetches series info from Xtream Codes
Validates episode exists
Checks for existing active downloads
Creates Xtream Codes download URL
Initiates Aria2 download with generated filename
Creates MediaDownloadRef record
Redirects to downloads page

Controller: SeriesDownloadController.php:34-67

Batch Episode Download

User posts to POST /series/{id}/download with episode list
System validates all episodes exist
Creates download URLs for all episodes
Initiates batch download via Aria2
Creates MediaDownloadRef records in transaction
Redirects to downloads page

Controller: SeriesDownloadController.php:69-119

Next Steps

Movies API

Learn about movie download endpoints

Series API

Learn about series download endpoints

Authentication

Understand download permissions

Endpoints

Models

Actions

​List Downloads

​Query Parameters

​Response

​Download Status Fields

​User Filtering

​Example

​Edit Download

​Path Parameters

​Request Body

​Response

​Action Validation

​Special Behaviors

​Example

​Delete Download

​Path Parameters

​Response

​Behavior

​Example

​Download Permissions

​Permission Logic

​Database Policy

​MediaDownloadRef Model

​Aria2 Integration

​Status Retrieval

​Download Operations

​Error Handling

​Download Actions

​Available Actions

​Download Creation Flow

​Movie Download

​Series Episode Download

​Batch Episode Download

​Next Steps

Movies API

Series API

Authentication

Build docs developers (and LLMs) love

List Downloads

Query Parameters

Response

Download Status Fields

User Filtering

Example

Edit Download

Path Parameters

Request Body

Response

Action Validation

Special Behaviors

Example

Delete Download

Path Parameters

Response

Behavior

Example

Download Permissions

Permission Logic

Database Policy

MediaDownloadRef Model

Aria2 Integration

Status Retrieval

Download Operations

Error Handling

Download Actions

Available Actions

Download Creation Flow

Movie Download

Series Episode Download

Batch Episode Download

Next Steps