From f4ffd23ed81740f00cde26c03ae38beb80228471 Mon Sep 17 00:00:00 2001
From: zebra <me@izebra.xyz>
Date: Mon, 8 Jun 2026 20:02:16 -0700
Subject: [PATCH] docs: REST API usage and Siri Shortcuts walkthrough

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
---
 README.md | 80 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)

diff --git a/README.md b/README.md
index a9c467f..c80c4a7 100644
--- a/README.md
+++ b/README.md
@@ -140,6 +140,86 @@ export LIDARR_API_KEY="your-lidarr-api-key"
 
 ---
 
+## 🌐 REST API (Docker)
+
+Run MusicFetch as an authenticated HTTP service inside your Lidarr Docker stack.
+A client POSTs a query; the server grabs the top hit non-interactively and runs
+the download as a background job you can poll. Every response includes a
+human-readable `message` (handy for Siri).
+
+### Configure & run
+
+Set the network name in `server/docker-compose.yml` to your existing Lidarr
+stack network, then:
+
+```bash
+export LIDARR_API_KEY="your-lidarr-key"
+export MUSICFETCH_API_KEY="a-long-random-secret"
+docker compose -f server/docker-compose.yml up -d --build
+```
+
+| Env var | Default | Purpose |
+| --- | --- | --- |
+| `MUSICFETCH_API_KEY` | *(required)* | Shared secret clients send as `X-API-Key`. |
+| `MUSICFETCH_PORT` | `6769` | Listen port. |
+| `LIDARR_URL` | `http://lidarr:8686` | Lidarr base URL (stack network). |
+| `LIDARR_API_KEY` | *(required for Lidarr)* | Lidarr API key. |
+| `MUSICFETCH_ROOT` | `/media/music` | Music output root (bind-mounted). |
+
+TLS is expected to be handled by your upstream reverse proxy; the container
+serves plain HTTP on `6769`.
+
+### Endpoints
+
+| Method | Path | Auth | Purpose |
+| --- | --- | --- | --- |
+| `GET` | `/health` | no | Liveness check. |
+| `POST` | `/fetch?q=...` | yes | Grab top hit; returns a `job_id`. |
+| `GET` | `/jobs/{id}` | yes | Poll job status. |
+
+`POST /fetch` params: `q` (required), `quality` (`best,320,m4a,opus,flac`),
+`source` (`auto,lidarr,youtube`).
+
+### curl examples
+
+```bash
+# Kick off a fetch
+curl -X POST 'https://mf.izebra.net/fetch?q=Under%20My%20Skin' \
+  -H 'X-API-Key: a-long-random-secret'
+# -> {"message":"Found 'Under My Skin' ... Downloading now.","job_id":"a1b2c3","status":"queued","hit":{...}}
+
+# Poll the job
+curl 'https://mf.izebra.net/jobs/a1b2c3' -H 'X-API-Key: a-long-random-secret'
+# -> {"message":"Finished downloading ...","status":"done","result":{...}}
+```
+
+### 🗣️ Siri Shortcuts integration
+
+Make a shortcut that fetches music by voice ("Hey Siri, fetch music").
+
+1. **Shortcuts app → New Shortcut.**
+2. Add **Ask for Input** → Input Type **Text**, prompt "What should I fetch?".
+   (Or use **Dictate Text** for fully spoken input.)
+3. Add **Text** action, set it to: `https://mf.izebra.net/fetch?q=` then insert
+   the **Provided Input** variable at the end. (Shortcuts URL-encodes query
+   variables automatically.)
+4. Add **Get Contents of URL**:
+   - **URL:** the Text variable from step 3.
+   - **Method:** `POST`.
+   - **Headers:** add one — key `X-API-Key`, value your `MUSICFETCH_API_KEY`.
+   - **Request Body:** leave as is (the query is in the URL).
+5. Add **Get Dictionary Value** → Get Value for **message** in **Contents of URL**.
+6. Add **Speak Text** → the Dictionary Value. Siri reads back
+   "Found '…' … Downloading now."
+7. (Optional) To confirm completion: add **Get Dictionary Value** for `job_id`,
+   **Wait** ~20 seconds, **Get Contents of URL** on
+   `https://mf.izebra.net/jobs/<job_id>` (same `X-API-Key` header), then
+   **Get Dictionary Value** `message` → **Speak Text** again.
+
+Rename the shortcut (e.g. "Fetch Music") — that phrase becomes the Siri trigger.
+
+---
+
 ## 🛠️ Contributing
 
 PRs welcome. This script is middleware around Lidarr + yt-dlp, not a Lidarr