Skip to main content
The WebSocket endpoint provides real-time bidirectional communication for starting downloads, receiving progress updates, viewing logs, and canceling operations.

​
Connection

Connect to the WebSocket endpoint at: 
ws://localhost:8000/ws
The server accepts the connection immediately and waits for commands.

​
Request format

Send JSON messages to control the download process:

​
Start download

​
command
string
required
Set to "start" to begin a manga download
​
url
string
required
The manga URL to download
{
  "command": "start",
  "url": "https://mangadex.org/title/abc123"
}

​
Cancel download

​
command
string
required
Set to "cancel" to stop the current download
{
  "command": "cancel"
}

​
Response messages

The server sends JSON messages with different types to communicate status, progress, logs, and errors.

​
Status message

Indicates the current state of the download process.
​
type
string
Set to "status"
​
status
string
Current status: "running", "completed", or "error"
​
filename
string
The generated PDF filename (only present when status is "completed")
{
  "type": "status",
  "status": "running"
}

{
  "type": "status",
  "status": "completed",
  "filename": "My Manga - Chapter 1-10.pdf"
}

​
Progress message

Provides real-time download progress updates.
​
type
string
Set to "progress"
​
current
integer
Number of chapters downloaded
​
total
integer
Total number of chapters to download
{
  "type": "progress",
  "current": 5,
  "total": 10
}

​
Log message

Streams detailed log messages during the download process.
​
type
string
Set to "log"
​
message
string
The log message text
{
  "type": "log",
  "message": "[INFO] Fetching manga metadata..."
}

{
  "type": "log",
  "message": "[SUCCESS] PDF Generated: My Manga - Chapter 1-10.pdf"
}

​
Error message

Reports errors that occur during processing.
​
type
string
Set to "error"
​
message
string
Error description
{
  "type": "error",
  "message": "No URL provided"
}

{
  "type": "error",
  "message": "Server is currently busy. Please try again later."
}

{
  "type": "error",
  "message": "An unexpected internal error occurred during processing."
}

​
Message flow

Here’s the typical sequence of messages when you start a download:
  1. Client: Send start command with URL
  2. Server: Status message ("running")
  3. Server: Multiple log messages with download progress
  4. Server: Multiple progress messages with chapter counts
  5. Server: Log message indicating PDF generation
  6. Server: Status message ("completed") with filename
If you cancel:
  1. Client: Send cancel command
  2. Server: Log message (“Cancelling…”)
  3. Server: Download stops gracefully

​
Security features

​
DoS protection

The server limits concurrent downloads to prevent resource exhaustion:
​
MAX_DOWNLOADS
integer
default:"3"
Maximum number of simultaneous downloads allowed
When the limit is reached, new download requests receive an error message asking you to try again later.

​
Information leakage prevention

Internal exceptions are logged server-side but sanitized error messages are sent to clients to prevent exposing sensitive system information.

​
Connection handling

The WebSocket connection remains open throughout the download process. The server handles disconnections gracefully and cleans up resources automatically.

Build docs developers (and LLMs) love

Get started for freeTalk to us