Document local scene search HTTP API

README.md

@@ -272,6 +272,56 @@ python -m scene_search.cli search "people walking down a street"
 
 Search output shows the stored caption as well as the Meilisearch and SigLIP diagnostic scores.
 
+## HTTP search API
+
+The Jellyfin plugin will talk to the same hybrid search logic through a small local FastAPI service.
+
+Configure it in `.env`:
+
+```env
+SCENE_API_HOST=127.0.0.1
+SCENE_API_PORT=8097
+SCENE_API_KEY=replace-with-a-random-secret
+```
+
+If Jellyfin and this project run on the same host, keeping the API bound to `127.0.0.1` is recommended.
+
+Start the service:
+
+```bash
+python -m scene_search.cli serve
+```
+
+The health endpoint is deliberately cheap and does not load SigLIP:
+
+```bash
+curl http://127.0.0.1:8097/api/health
+```
+
+The first real search loads SigLIP and keeps it resident for later requests:
+
+```bash
+curl -H "Authorization: Bearer replace-with-a-random-secret" \
+  "http://127.0.0.1:8097/api/search?q=woman%20standing%20outside"
+```
+
+`/api/search` searches Jellyfin-backed documents only and returns two views of the same ranking:
+
+- `items`: one de-duplicated result per Jellyfin item, intended for Jellyfin's normal search provider.
+- `scenes`: timestamped scene hits with captions and scores, intended for the later Scene Search page.
+
+Each scene contains its Jellyfin item/media-source/library IDs, item type, timestamp, caption, tags, Meilisearch ranking score and SigLIP diagnostic score.
+
+Cached Trickplay thumbnails are available through:
+
+```text
+GET /api/frames/{frame_id}/thumbnail
+```
+
+When `SCENE_API_KEY` is set, search and thumbnail endpoints accept either `Authorization: Bearer <key>` or `X-Scene-Search-Key: <key>`. `/api/health` remains unauthenticated for local service monitoring.
+
+The API intentionally runs with one worker. Multiple workers would each load their own copy of the embedding model into GPU memory.
+
 ## Removing indexed sources
 
 Old prototype clips and Jellyfin-backed items are stored with different source kinds.