Search API - REST Endpoints

API Design: REST Endpoints

Overview

The api.py provides a lightweight FastAPI service that serves as the search backend and static file server. It exposes endpoints for semantic search, file retrieval, and health monitoring.

Base URL

http://127.0.0.1:8000

Endpoints

GET /

Description: Serves the main frontend HTML file.

Response: text/html

---

GET /search

Description: Performs semantic search on the indexed vault using a natural language query.

Parameters:

Parameter	Type	Required	Description
q	string	Yes	The semantic search query (e.g., “sunset at the beach”)
limit	integer	No	Number of results to return (default: 12)

Response:

{
  "results": [
    {
      "id": "vault/IMG-20250514-WA0055.jpg",
      "score": 0.92,
      "metadata": {
        "full_path": "D:\\....\\Local-Semantic-Media-Search\\vault\\IMG-20250514-WA0055.jpg",
        "thumbnail_path": ".cache/thumbnails/abc123.webp",
        "filename": "IMG-20250514-WA0055.jpg",
        "mtime": 1747228800.0,
        "file_type": "image"
      }
    }
  ]
}

Notes:

• Results are filtered by cosine distance threshold (0.7).
• The score field is the cosine similarity (1 - distance).

---

GET /file

Description: Streams the original high-resolution image or video file.

Parameters:

Parameter	Type	Required	Description
path	string	Yes	Full absolute path to the image or video file

Response: Binary media stream (image/jpeg, video/mp4, etc.) or 404 Not Found.

---

GET /health

Description: Health check endpoint for monitoring and readiness probes.

Response:

{
  "status": "ok",
  "device": "cuda"
}

---

GET /thumbnails/*

Description: Serves pre-computed 300x300 WebP thumbnails for search results.

Mount point: /thumbnails

Local directory: .cache/thumbnails/

---

CORS Policy

{
  "allow_origins": ["*"],
  "allow_credentials": true,
  "allow_methods": ["*"],
  "allow_headers": ["*"]
}

Warning: This is configured for local use. Do not deploy to production without restricting allow_origins.

Error Handling

Status Code	Condition
404 Not Found	Requested file path does not exist on disk
500 Internal Server Error	Engine not initialized at /search

Related Components

• Qwen3VL Embeddings – Used for text query embedding
• Image Indexing Pipeline – Populates the database queried by /search
• Privacy & Security – CORS and local-only guarantees

---

Last Updated: 2026-06-17