Browser requests: Authenticated by X-Requested-With: XMLHttpRequest header (set automatically by the frontend)
External requests: Require X-Api-Key header if MEDIARIP__SERVER__API_KEY is configured
Admin endpoints: Require Authorization: Basic <base64(user:pass)> header

Downloads

`POST /api/downloads`

Create a download job.

{"url": "https://youtube.com/watch?v=xxx", "format_id": "137+140"}

Returns job object. For playlists, creates multiple jobs and returns the first.

`GET /api/downloads`

List jobs for the current session.

`DELETE /api/downloads/{job_id}`

Cancel a job, delete the downloaded file, notify SSE subscribers.

`POST /api/url-info`

Extract URL metadata without downloading.

{"url": "https://youtube.com/watch?v=xxx"}

Returns: {title, is_playlist, is_audio_only, duration}

Formats

`GET /api/formats?url=...`

Get available download formats for a URL. Returns array of format objects with resolution, codec, filesize info.

Server-Sent Events

`GET /api/events`

EventSource stream. Events:

Event	Data	Description
`init`	`{jobs: [...]}`	All non-terminal jobs (replay on reconnect)
`job_update`	`{job: {...}}`	Job status/progress changed
`job_removed`	`{job_id: "..."}`	Job was deleted
`ping`	`{}`	Keepalive (every 15s)

Health

`GET /api/health`

{"status": "ok", "version": "1.0.0", "yt_dlp_version": "2026.3.17", "uptime": 3600, "queue_depth": 2}

System

`GET /api/config/public`

Frontend configuration (theme settings, session mode, welcome message). No auth required.

Cookies

`POST /api/cookies`

Upload Netscape-format cookies.txt for the current session. Used for authenticated downloads.

`DELETE /api/cookies`

Remove uploaded cookies for the current session.

Themes

`GET /api/themes`

List custom themes from /themes volume.

`GET /api/themes/{theme_id}/theme.css`

Serve custom theme CSS file.

Admin

All admin endpoints require authentication.

`GET /api/admin/status`

{"enabled": true, "setup_complete": true}

`POST /api/admin/setup`

First-run password creation (only works when no password is set).

`GET /api/admin/sessions`

List all sessions with job counts.

`GET /api/admin/storage`

Disk usage statistics for download directory.

`POST /api/admin/purge`

Manually trigger cleanup of old downloads.

`POST /api/admin/password`

Change admin password.

`POST /api/admin/api-key`

Generate or revoke API key.

`GET /api/admin/error-log`

View error log entries.

`DELETE /api/admin/error-log`

Clear error log.