API Endpoints for ReClip: Complete REST Reference and Usage Examples

ReClip exposes six REST endpoints under the /api/ prefix that handle video metadata extraction, playlist parsing, asynchronous downloads, and file retrieval, with all routes defined in app.py using Flask decorators.

ReClip is an open-source video downloading service built on Flask that provides a lightweight REST interface for processing media URLs. The averygan/reclip repository implements a straightforward JSON API architecture that bridges frontend interactions with yt-dlp backend operations. Understanding the API endpoints for ReClip enables developers to integrate video downloading capabilities directly into custom applications without relying on the web interface.

Core API Endpoint Reference

All routes except the root view are prefixed with /api/ and return JSON responses (or binary streams for file delivery). The following sections detail each endpoint's purpose, HTTP method, and implementation location in app.py.

Root Endpoint (GET /)

The root route serves the main web interface rather than JSON data.

• Purpose: Serves templates/index.html to browser clients
• Implementation: Lines 92‑94 in app.py
• Response: HTML document

Video Metadata (POST /api/info)

This endpoint extracts comprehensive metadata from a single video URL before downloading.

• Purpose: Accepts a video URL and returns metadata including title, thumbnail, duration, uploader, and available format options
• Implementation: Lines 97‑141 in app.py
• Request Body: {"url": "https://..."}
• Response: JSON object containing video details and format array

Playlist Parsing (POST /api/playlist)

Use this route to unpack playlist URLs into individual video entries.

• Purpose: Accepts a playlist URL and returns an array of contained video URLs
• Implementation: Lines 143‑162 in app.py
• Request Body: {"url": "https://..."}
• Response: JSON array of video URL strings

Download Initialization (POST /api/download)

Initiates background processing jobs for media extraction.

• Purpose: Starts a background download job and returns a unique job_id for polling
• Implementation: Lines 166‑185 in app.py
• Request Body: {"url": "https://...", "format": "video"} (format options: "video" or "audio")
• Response: {"job_id": "uuid-string"}

Job Status Monitoring (GET /api/status/<job_id>)

Poll this endpoint to track asynchronous download progress.

• Purpose: Returns the current state of a download job (downloading, done, or error) and the final filename when complete
• Implementation: Lines 187‑196 in app.py
• URL Parameter: job_id (UUID returned from /api/download)
• Response: {"status": "done", "filename": "video.mp4"}

File Retrieval (GET /api/file/<job_id>)

Streams the completed media file to the client once processing finishes.

• Purpose: Streams the downloaded file as an attachment
• Implementation: Lines 199‑204 in app.py
• URL Parameter: job_id
• Response: Binary file stream with Content-Disposition: attachment header

Backend Implementation Architecture

The ReClip API leverages Flask's decorator-based routing system combined with subprocess management for media handling.

Route Registration: All endpoints use Flask's @app.route decorator with explicit HTTP method constraints (either methods=['GET'] or methods=['POST']).

yt-dlp Integration: The application invokes yt-dlp via subprocess.run() calls within the route handlers to handle actual video extraction and format parsing.

Job State Management: ReClip maintains an in-memory global jobs dictionary that tracks active download states, file paths, and error messages. This dictionary persists for the lifetime of the Flask process.

Storage: Completed downloads are written to a downloads/ directory relative to the application root. The system cleans up extraneous temporary files once a job reaches the done state.

Practical Usage Examples

The following curl commands demonstrate complete interaction flows with the API endpoints for ReClip. Replace https://your-reclip-host with your actual deployment URL.

Fetching Video Metadata

curl -X POST -H "Content-Type: application/json" \
     -d '{"url":"https://www.youtube.com/watch?v=abcd1234"}' \
     https://your-reclip-host/api/info

Extracting Playlist URLs

curl -X POST -H "Content-Type: application/json" \
     -d '{"url":"https://www.youtube.com/playlist?list=PLxyz"}' \
     https://your-reclip-host/api/playlist

Starting a Download Job

curl -X POST -H "Content-Type: application/json" \
     -d '{"url":"https://www.youtube.com/watch?v=abcd1234","format":"video"}' \
     https://your-reclip-host/api/download

Checking Download Status

curl https://your-reclip-host/api/status/<job_id>

Retrieving the Completed File

curl -OJ https://your-reclip-host/api/file/<job_id>

Key Source Files

The ReClip codebase organizes its API logic across the following locations:

• app.py: Core Flask application containing all route definitions (lines 92‑204) and the download worker logic
• templates/index.html: Front-end UI template served at the root endpoint
• requirements.txt: Python dependency specification including Flask and supporting libraries
• Dockerfile / docker-compose.yml: Container definitions for production deployments

Summary

• ReClip provides six REST endpoints: one HTML-serving root route (/) and five JSON API routes under /api/ for metadata, playlists, downloads, status checks, and file retrieval.
• All API routes are defined in app.py using Flask decorators, with specific line ranges documented for each handler (lines 92‑204).
• The service uses yt-dlp via subprocess calls to handle video extraction, with jobs tracked in a global dictionary and files stored in the downloads/ folder.
• Download processing is asynchronous: Clients must poll /api/status/<job_id> after initiating a job via /api/download, then fetch results from /api/file/<job_id>.

Frequently Asked Questions

What base URL prefix do the ReClip API endpoints use?

All JSON API endpoints reside under the /api/ path prefix (e.g., /api/info, /api/download), while the root endpoint / serves the HTML interface. This structure separates API traffic from web UI delivery.

How does ReClip handle asynchronous download processing?

When you POST to /api/download, ReClip spawns a background thread that executes yt-dlp and stores progress in a global jobs dictionary keyed by UUID. You must poll /api/status/<job_id> to monitor the downloading, done, or error states before retrieving the file.

What format options are available when starting a download?

The /api/download endpoint accepts a format parameter in the JSON body with two valid string values: "video" for combined video+audio downloads or "audio" for audio-only extraction. The default behavior depends on the frontend implementation if omitted.

Where does ReClip store downloaded files during processing?

Completed files are written to a downloads/ directory relative to the application root, as implemented in app.py lines 199‑204. The application serves these files via the /api/file/<job_id> endpoint and cleans up temporary metadata once jobs finish.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}