# API Endpoints for ReClip: Complete REST Reference and Usage Examples

> Explore ReClip API endpoints for video metadata extraction playlist parsing asynchronous downloads and file retrieval. Get complete REST reference and usage examples.

- Repository: [Avery Gan/reclip](https://github.com/averygan/reclip)
- Tags: api-reference
- Published: 2026-09-05

---

**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`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/app.py).

### Root Endpoint (GET `/`)

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

- **Purpose**: Serves [`templates/index.html`](https://github.com/averygan/reclip/blob/main/templates/index.html) to browser clients
- **Implementation**: Lines 92‑94 in [`app.py`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/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

```bash
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

```bash
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

```bash
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

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

```

### Retrieving the Completed File

```bash
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`](https://github.com/averygan/reclip/blob/main/app.py)**: Core Flask application containing all route definitions (lines 92‑204) and the download worker logic
- **[`templates/index.html`](https://github.com/averygan/reclip/blob/main/templates/index.html)**: Front-end UI template served at the root endpoint
- **[`requirements.txt`](https://github.com/averygan/reclip/blob/main/requirements.txt)**: Python dependency specification including Flask and supporting libraries
- **`Dockerfile`** / **[`docker-compose.yml`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/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`](https://github.com/averygan/reclip/blob/main/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.