musicfetch/docs/superpowers/specs/2026-06-08-musicfetch-rest-api-design.md

MusicFetch REST API — Design

Date: 2026-06-08 Status: Approved

Context & Goal

musicfetch is a single-file CLI that searches Lidarr + YouTube Music and grabs music. We want to trigger it remotely (notably from iOS Siri Shortcuts) via a small authenticated HTTP API, dockerized to run inside the existing Plex/Lidarr Docker stack on the Plex server.

Vision: a client POSTs a query with an API key; the server runs musicfetch non-interactively, grabs the top hit, and returns a human-readable response (speakable by Siri). Downloads run as async background jobs the client can poll — no fire-and-forget.

Constraints & Decisions

• musicfetch stays a standalone single-file binary — no changes to it. The API imports it as a module (it guards if __name__ == "__main__", so importing is side-effect free) and reuses its Hit model + build_combined_hits, pick, act_youtube, act_lidarr_album, act_lidarr_artist.
• Async jobs (not synchronous, not fire-and-forget). POST returns immediately with a job_id; client polls GET /jobs/{id}.
• Runs in the existing Lidarr stack: joins the stack network → reaches http://lidarr:8686; bind-mounts the host /media/music. Self-contained image (musicfetch ships inside it); nothing external required at runtime besides the volume + Lidarr network.
• Auth: shared secret via X-API-Key header, compared to MUSICFETCH_API_KEY.
• TLS: terminated by an upstream reverse proxy already on the user's network. The container speaks plain HTTP.
• Port: configurable via MUSICFETCH_PORT, default 6769.
• Siri-friendly: every JSON response carries a top-level human message string.
• Personal-scale: in-memory job store (lost on restart, acceptable). No DB/Redis.

Architecture

musicfetch/
├── musicfetch            # unchanged standalone binary
├── README.md             # + API usage + Siri Shortcuts walkthrough
├── docs/superpowers/specs/2026-06-08-musicfetch-rest-api-design.md
└── server/               # the REST API
    ├── app.py            # FastAPI app: routes, auth dependency
    ├── jobs.py           # Job model, in-memory store, ThreadPoolExecutor worker
    ├── mf.py             # importlib loader: loads ../musicfetch as a module
    ├── requirements.txt  # fastapi, uvicorn, requests, ytmusicapi, rich
    ├── Dockerfile
    └── docker-compose.yml

Components

• server/mf.py — loads the sibling musicfetch file via importlib.util.spec_from_file_location (no .py extension). Re-exports the reused symbols. Single seam between API and CLI. Sets nothing global beyond what env already provides (LIDARR_URL, LIDARR_API_KEY, MUSICFETCH_ROOT).
• server/jobs.py — Job dataclass (id, status, hit, result, error, created_at, updated_at); JOBS: dict[str, Job]; a module-level ThreadPoolExecutor(max_workers=2). submit_fetch(hit, quality, root) enqueues a task that runs the blocking act_* call and updates the job. Optional cap on dict size to avoid unbounded growth.
• server/app.py — FastAPI app. API-key dependency. Routes below.

Data flow

1. POST /fetch (authed) → build hits via build_combined_hits(q, limit=10, yt_first=(source=="youtube"), lidarr_only=(source=="lidarr"), yt_only=(source=="youtube")); choose top via pick(hits, q, noninteractive=True, yt_first=...).
2. No hits → 404 {"message": "No results found for '<q>'."}.
3. Create Job (queued), submit worker task, return job + hit + message.
4. Worker sets running, calls the right act_*, captures result/exception, sets done / failed, updates message.
5. Client polls GET /jobs/{id}.

API Contract

All non-health routes require header X-API-Key. Bad/missing → 401 {"message": "Invalid API key."}.

POST /fetch

Params (JSON body or query string):

• q (required) — free-form query.
• quality (optional) — one of musicfetch's QUALITY_CHOICES (best,320,m4a,opus,flac); default best.
• source (optional) — auto (default, Lidarr-first), lidarr, youtube.

Success 200:

{
  "message": "Found 'Under My Skin' by Avril Lavigne on YouTube Music. Downloading now.",
  "job_id": "a1b2c3",
  "status": "queued",
  "hit": { "source": "youtube", "artist": "Avril Lavigne",
           "album": "Under My Skin", "title": "Together", "year": "2004" }
}

Errors: 404 no hits; 422 missing q (FastAPI default, also wrapped to include message); 401 bad key.

GET /jobs/{id}

200:

{
  "message": "Finished downloading 'Under My Skin' by Avril Lavigne.",
  "job_id": "a1b2c3",
  "status": "done",
  "hit": { "...": "..." },
  "result": { "path": "/media/music/Avril Lavigne/youtube", "lidarr_album_id": null },
  "error": null
}

status: queued → running → done | failed. Unknown id → 404 {"message": "No such job."}. On failed, message is a speakable explanation and error carries detail.

GET /health

No auth. {"status": "ok"}.

Error Handling

• 401 invalid/missing key; 404 no hits / unknown job; 422 missing q; 500 unexpected — all bodies include a message string.
• Download/Lidarr failures surface in the job (status: failed), never crash the HTTP request that started them.
• musicfetch's existing Lidarr→YouTube fallthrough is preserved (worker uses the same act_lidarr_album path).

Docker

• Dockerfile: python:3.12-slim; apt-get install -y ffmpeg; pip install yt-dlp -r server/requirements.txt; COPY musicfetch ./musicfetch + COPY server ./server; CMD ["sh","-c","uvicorn server.app:app --host 0.0.0.0 --port ${MUSICFETCH_PORT:-6769}"]. Build context = repo root.
• docker-compose.yml: service musicfetch-api; attach to the existing Lidarr stack network (declared external: true); volumes: /media/music:/media/music; ports: "6769:6769"; env LIDARR_URL=http://lidarr:8686, LIDARR_API_KEY, MUSICFETCH_API_KEY, MUSICFETCH_ROOT=/media/music, MUSICFETCH_PORT=6769.

Testing

• Unit: API-key dependency (401 paths); /fetch with musicfetch core mocked to return a canned Hit — assert job created, response shape, message present; job lifecycle queued→running→done and →failed on worker exception; /jobs/{id} unknown-id 404; /health.
• No real network or downloads in tests (mock build_combined_hits/act_*).
• Manual smoke after deploy: curl -H 'X-API-Key: ...' -X POST 'http://host:6769/fetch?q=Under My Skin' → poll /jobs/{id}.

README additions

• API section: env vars, run via docker-compose, all endpoints with curl examples.
• Siri Shortcuts walkthrough (research current "Get Contents of URL" UI): build a shortcut that takes dictated/typed text, POSTs to /fetch with the X-API-Key header and q, reads back the message via "Speak Text", and (optional) waits then GETs /jobs/{id} to confirm completion.

Out of Scope (YAGNI)

Persistent job store, multi-user keys, rate limiting, in-container TLS, a web UI, download progress streaming.