diff --git a/API-Reference.-.md b/API-Reference.-.md
new file mode 100644
index 0000000..c2c4dfc
--- /dev/null
+++ b/API-Reference.-.md
@@ -0,0 +1,144 @@
+# API Reference
+
+| Meta | Value |
+|------|-------|
+| **Repo** | `xpltdco/media-rip` |
+| **Page** | `API-Reference` |
+| **Audience** | developers, agents |
+| **Last Updated** | 2026-04-04 |
+| **Status** | current |
+
+## Base URL
+
+Local: `http://localhost:8000/api` | Production: `https://mediarip.xpltd.co/api`
+
+## Authentication
+
+- **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.
+
+```json
+{"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.
+
+```json
+{"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`
+
+```json
+{"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`
+
+```json
+{"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.
\ No newline at end of file