Skip to main content
The /events endpoint provides a real-time stream of download events using Server-Sent Events (SSE). This allows you to monitor all download activity without polling.

​
GET /events

Subscribe to a stream of real-time download events.

​
Request

curl http://localhost:1700/events \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Accept: text/event-stream"

​
Response

The response is a continuous stream of Server-Sent Events. Each event has a type and JSON data payload. Headers:
  • Content-Type: text/event-stream
  • Cache-Control: no-cache
  • Connection: keep-alive
Event Format: 
event: <event-type>
data: <json-payload>

​
Event Types

The API emits the following event types:

​
progress

Emitted periodically during active downloads with progress updates.
​
DownloadID
string
Unique identifier for the download.
​
Downloaded
integer
Number of bytes downloaded so far.
​
Total
integer
Total file size in bytes.
​
Speed
number
Current download speed in bytes per second.
​
Elapsed
integer
Time elapsed in nanoseconds since download started.
​
ActiveConnections
integer
Number of active connections for this download.
​
ChunkBitmap
array
Binary bitmap representing download chunk status.
​
BitmapWidth
integer
Width of the chunk bitmap for rendering.
​
ActualChunkSize
integer
Size of each chunk in bytes.
​
ChunkProgress
array
Array of bytes downloaded for each chunk.
Example: 
event: progress
data: {"DownloadID":"abc-123","Downloaded":52428800,"Total":104857600,"Speed":10485760,"Elapsed":5000000000,"ActiveConnections":8,"ChunkBitmap":[],"BitmapWidth":0,"ActualChunkSize":0,"ChunkProgress":[]}

​
started

Emitted when a download begins (after metadata is fetched).
​
DownloadID
string
Unique identifier for the download.
​
URL
string
The URL being downloaded.
​
Filename
string
Name of the file being downloaded.
​
Total
integer
Total file size in bytes.
​
DestPath
string
Full path to the destination file.
Example: 
event: started
data: {"DownloadID":"abc-123","URL":"https://example.com/file.zip","Filename":"file.zip","Total":104857600,"DestPath":"/home/user/downloads/file.zip"}

​
complete

Emitted when a download finishes successfully.
​
DownloadID
string
Unique identifier for the download.
​
Filename
string
Name of the completed file.
​
Elapsed
integer
Total time taken in nanoseconds.
​
Total
integer
Total bytes downloaded.
​
AvgSpeed
number
Average download speed in bytes per second.
Example: 
event: complete
data: {"DownloadID":"abc-123","Filename":"file.zip","Elapsed":10000000000,"Total":104857600,"AvgSpeed":10485760}

​
error

Emitted when a download encounters an error.
​
DownloadID
string
Unique identifier for the download.
​
Filename
string
Name of the file that failed.
​
Err
string
Error message describing what went wrong.
Example: 
event: error
data: {"DownloadID":"abc-123","Filename":"file.zip","Err":"connection timeout"}

​
paused

Emitted when a download is paused.
​
DownloadID
string
Unique identifier for the download.
​
Filename
string
Name of the paused file.
​
Downloaded
integer
Number of bytes downloaded before pausing.
Example: 
event: paused
data: {"DownloadID":"abc-123","Filename":"file.zip","Downloaded":52428800}

​
resumed

Emitted when a paused download is resumed.
​
DownloadID
string
Unique identifier for the download.
​
Filename
string
Name of the resumed file.
Example: 
event: resumed
data: {"DownloadID":"abc-123","Filename":"file.zip"}

​
queued

Emitted when a download is added to the queue.
​
DownloadID
string
Unique identifier for the download.
​
Filename
string
Name of the queued file.
​
URL
string
The URL to download.
​
DestPath
string
Destination path for the file.
Example: 
event: queued
data: {"DownloadID":"abc-123","Filename":"file.zip","URL":"https://example.com/file.zip","DestPath":"/home/user/downloads/file.zip"}

​
removed

Emitted when a download is deleted.
​
DownloadID
string
Unique identifier for the download.
​
Filename
string
Name of the removed file.
Example: 
event: removed
data: {"DownloadID":"abc-123","Filename":"file.zip"}

​
request

Emitted when a download is requested (e.g., from a browser extension) and may need user confirmation.
​
ID
string
Request identifier.
​
URL
string
The requested URL.
​
Filename
string
Suggested filename.
​
Path
string
Suggested destination path.
​
Mirrors
array
Array of mirror URLs.
​
Headers
object
Custom HTTP headers for the request.
Example: 
event: request
data: {"ID":"req-123","URL":"https://example.com/file.zip","Filename":"file.zip","Path":"/downloads","Mirrors":[],"Headers":{}}

​
system

Emitted for system-level log messages.
​
Message
string
System log message.
Example: 
event: system
data: {"Message":"Server started on port 1700"}

​
Examples

const eventSource = new EventSource('http://localhost:1700/events', {
  headers: {
    'Authorization': 'Bearer YOUR_TOKEN'
  }
});

eventSource.addEventListener('progress', (e) => {
  const data = JSON.parse(e.data);
  console.log(`Progress: ${data.Downloaded}/${data.Total} bytes`);
});

eventSource.addEventListener('complete', (e) => {
  const data = JSON.parse(e.data);
  console.log(`Download complete: ${data.Filename}`);
});

eventSource.addEventListener('error', (e) => {
  const data = JSON.parse(e.data);
  console.error(`Download error: ${data.Err}`);
});

eventSource.onerror = (error) => {
  console.error('SSE connection error:', error);
};

​
Building a Real-time Dashboard

Here’s an example of building a live download dashboard: 
const downloads = new Map();

const eventSource = new EventSource('http://localhost:1700/events', {
  headers: { 'Authorization': 'Bearer YOUR_TOKEN' }
});

// Track all downloads
eventSource.addEventListener('queued', (e) => {
  const data = JSON.parse(e.data);
  downloads.set(data.DownloadID, {
    id: data.DownloadID,
    filename: data.Filename,
    status: 'queued',
    progress: 0
  });
  updateUI();
});

eventSource.addEventListener('started', (e) => {
  const data = JSON.parse(e.data);
  const download = downloads.get(data.DownloadID);
  if (download) {
    download.status = 'downloading';
    download.total = data.Total;
    updateUI();
  }
});

eventSource.addEventListener('progress', (e) => {
  const data = JSON.parse(e.data);
  const download = downloads.get(data.DownloadID);
  if (download) {
    download.downloaded = data.Downloaded;
    download.speed = data.Speed;
    download.progress = (data.Downloaded / data.Total) * 100;
    updateUI();
  }
});

eventSource.addEventListener('complete', (e) => {
  const data = JSON.parse(e.data);
  const download = downloads.get(data.DownloadID);
  if (download) {
    download.status = 'complete';
    download.progress = 100;
    updateUI();
  }
});

eventSource.addEventListener('paused', (e) => {
  const data = JSON.parse(e.data);
  const download = downloads.get(data.DownloadID);
  if (download) {
    download.status = 'paused';
    updateUI();
  }
});

function updateUI() {
  // Update your UI with the downloads Map
  console.log('Active downloads:', downloads.size);
}

​
Connection Management

SSE connections remain open indefinitely. The connection will close if:
  • The client disconnects
  • The server shuts down
  • A network error occurs
Most SSE clients automatically reconnect when the connection drops.

​
Use Cases

  • Real-time Dashboards: Build web UIs showing live download progress
  • Monitoring: Track all download activity in real-time
  • Notifications: Alert users when downloads complete or fail
  • Analytics: Collect download metrics and statistics
  • Integration: Trigger actions based on download events
  • Download - Start downloads that emit events
  • List - Get current snapshot of all downloads
  • Pause - Pause downloads (emits paused event)
  • Resume - Resume downloads (emits resumed event)