API Reference

MeTube provides a simple REST-like API over HTTP and a real-time API over Socket.IO for managing downloads and receiving updates.

HTTP API

The following endpoints are available. The base path is determined by the URL_PREFIX configuration, which defaults to /.

POST /add

Adds a new video or playlist to the download queue.

Request Body (JSON):

{
  "url": "string",
  "quality": "string",
  "format": "string | null",
  "folder": "string | null",
  "custom_name_prefix": "string | null",
  "playlist_strict_mode": "boolean | null",
  "playlist_item_limit": "number | null",
  "auto_start": "boolean | null"
}
  • url: The URL of the video or playlist.
  • quality: The desired quality (e.g., 'best', '1080', 'audio').
  • format: The file format (e.g., 'any', 'mp4', 'mp3').
  • folder: The subfolder to download to.
  • custom_name_prefix: A string to prepend to the filename.
  • playlist_strict_mode: Whether to enforce strict playlist URLs.
  • playlist_item_limit: The maximum number of items to download from a playlist.
  • auto_start: If false, the download is added in a 'pending' state.

Response:

A JSON object indicating success or failure.

{"status": "ok"}
// or
{"status": "error", "msg": "Error message"}

POST /delete

Cancels items from the 'Downloading' queue or clears them from the 'Completed' list.

Request Body (JSON):

{
  "ids": ["string"],
  "where": "string"
}
  • ids: An array of download URLs (which act as IDs).
  • where: Either 'queue' to cancel active/pending downloads or 'done' to clear completed/failed downloads.

POST /start

Manually starts one or more downloads that are in a 'pending' state.

Request Body (JSON):

{
  "ids": ["string"]
}
  • ids: An array of pending download URLs to start.

GET /history

Retrieves the current state of all downloads.

Response:

A JSON object containing arrays for queue, done, and pending downloads.

{
  "done": [ /* array of download objects */ ],
  "queue": [ /* array of download objects */ ],
  "pending": [ /* array of download objects */ ]
}

GET /version

Returns the current version of MeTube and its yt-dlp engine.

Response:

{
  "yt-dlp": "2025.09.05",
  "version": "2024.09.05"
}

Socket.IO API

MeTube uses Socket.IO for real-time communication with clients. The server emits events to notify clients of changes.

  • connect: Emitted when a client connects.
  • all: Sent to a newly connected client, containing the entire current state of all queues (queue, done, pending).
  • configuration: Sent to a newly connected client, containing the server's configuration.
  • custom_dirs: Sent to a newly connected client, containing the list of available custom directories.
  • added: Emitted when a new download is added to the queue. The payload is a single Download object.
  • updated: Emitted when a download's status (progress, speed, ETA) changes. The payload is the updated Download object.
  • completed: Emitted when a download finishes (successfully or not). It is removed from the queue and added to the done list. The payload is the final Download object.
  • canceled: Emitted when a download is canceled from the queue. The payload is the ID (URL) of the download.
  • cleared: Emitted when a download is cleared from the completed list. The payload is the ID (URL) of the download.
  • ytdl_options_changed: Emitted when the YTDL_OPTIONS_FILE is modified on the server.