docs: complete API dictionary v1.0.0 (55 endpoints)

docs_v1.0/API_V1.0.0/API_DICTIONARY_V1.0.0.md

@@ -0,0 +1,122 @@
+# API Dictionary v1.0.0
+
+53 endpoints across 10 modules. Auth: `X-API-Key` header.
+
+## Legend
+
+- `→` direction of data flow
+- `POST` typically requires JSON body
+- All endpoints return JSON unless noted
+
+---
+
+## Core (server.rs)
+
+| # | Method | Route | Description |
+|---|--------|-------|-------------|
+| 1 | GET | `/health` | Server health (ok/degraded) |
+| 2 | GET | `/health/detailed` | Per-service health + latency |
+| 3 | POST | `/api/v1/auth/login` | Username/password → API key |
+| 4 | POST | `/api/v1/auth/logout` | Invalidate session |
+| 5 | GET | `/api/v1/stats/ingest` | Ingest statistics |
+| 6 | GET | `/api/v1/stats/sftpgo` | SFTPGo service status |
+| 7 | GET | `/api/v1/stats/inference` | LLM/embedding health |
+| 8 | POST | `/api/v1/files/register` | Register video file → UUID |
+| 9 | POST | `/api/v1/unregister` | Delete file + all data |
+| 10 | GET | `/api/v1/files/scan` | Scan directory for new files |
+| 11 | GET | `/api/v1/file/:file_uuid/probe` | ffprobe metadata |
+| 12 | POST | `/api/v1/file/:file_uuid/process` | Start processing pipeline |
+| 13 | GET | `/api/v1/file/:file_uuid/chunks` | List pre-chunks for file |
+| 14 | GET | `/api/v1/progress/:uuid` | Processing progress |
+| 15 | GET | `/api/v1/jobs` | List monitor jobs (filterable by status) |
+| 16 | POST | `/api/v1/config/cache` | Toggle Redis cache |
+| 17 | POST | `/api/v1/search/visual` | Search visual chunks |
+| 18 | POST | `/api/v1/search/visual/class` | Search by object class |
+| 19 | POST | `/api/v1/search/visual/density` | Search by spatial density |
+| 20 | POST | `/api/v1/search/visual/combination` | Combined visual search |
+| 21 | POST | `/api/v1/search/visual/stats` | Visual chunk statistics |
+
+## File/Identity (identity_api.rs)
+
+| # | Method | Route | Description |
+|---|--------|-------|-------------|
+| 22 | GET | `/api/v1/files` | List registered files (paginated) |
+| 23 | GET | `/api/v1/file/:file_uuid` | Single file detail |
+| 24 | GET | `/api/v1/file/:file_uuid/identities` | Identities in this file |
+| 25 | GET | `/api/v1/identities` | List all identities |
+| 26 | POST | `/api/v1/identity` | Register new identity |
+| 27 | GET | `/api/v1/identity/:uuid` | Identity detail |
+| 28 | DELETE | `/api/v1/identity/:uuid` | Delete identity |
+| 29 | GET | `/api/v1/identity/:uuid/files` | Files for an identity |
+| 30 | GET | `/api/v1/identity/:uuid/chunks` | Chunks for an identity |
+| 31 | POST | `/api/v1/resource/register` | Register processing resource |
+| 32 | POST | `/api/v1/resource/heartbeat` | Resource heartbeat |
+| 33 | GET | `/api/v1/resources` | List all resources |
+
+## Identity Binding (identity_binding.rs)
+
+| # | Method | Route | Description |
+|---|--------|-------|-------------|
+| 34 | POST | `/api/v1/identity/:uuid/bind` | Bind face → identity |
+| 35 | POST | `/api/v1/identity/:uuid/unbind` | Unbind face from identity |
+| 36 | POST | `/api/v1/identity/:from/mergeinto` | Merge identities |
+
+## Face Candidates (identities.rs)
+
+| # | Method | Route | Description |
+|---|--------|-------|-------------|
+| 37 | GET | `/api/v1/faces/candidates` | Unbound face gallery (paginated) |
+
+## Search (search.rs + universal_search.rs)
+
+| # | Method | Route | Description |
+|---|--------|-------|-------------|
+| 38 | POST | `/api/v1/search/smart` | Semantic search (EmbeddingGemma + pgvector) |
+| 39 | POST | `/api/v1/search/universal` | BM25 keyword search (requires uuid) |
+| 40 | POST | `/api/v1/search/frames` | Frame-level search |
+
+## Trace (trace_agent_api.rs)
+
+| # | Method | Route | Description |
+|---|--------|-------|-------------|
+| 41 | POST | `/api/v1/file/:uuid/face_trace/sortby` | List traces (sorted/filtered) |
+| 42 | GET | `/api/v1/file/:uuid/trace/:id/faces` | Single trace detections + interpolation |
+
+## Media (media_api.rs)
+
+| # | Method | Route | Description |
+|---|--------|-------|-------------|
+| 43 | GET | `/api/v1/file/:uuid/thumbnail` | Frame JPEG (with optional crop) |
+| 44 | GET | `/api/v1/file/:uuid/video` | Raw video stream |
+| 45 | GET | `/api/v1/file/:uuid/video/bbox` | Bbox overlay video |
+| 46 | GET | `/api/v1/file/:uuid/trace/:id/video` | Trace clip with bbox |
+
+## Agents (agent_api.rs + five_w1h_agent_api.rs + identity_agent_api.rs)
+
+| # | Method | Route | Description |
+|---|--------|-------|-------------|
+| 47 | POST | `/api/v1/agents/translate` | AI text translation |
+| 48 | POST | `/api/v1/agents/5w1h/analyze` | Single chunk 5W1H analysis |
+| 49 | POST | `/api/v1/agents/5w1h/batch` | Batch 5W1H analysis |
+| 50 | GET | `/api/v1/agents/5w1h/status` | 5W1H job status |
+| 51 | POST | `/api/v1/agents/identity/analyze` | Identity analysis |
+| 52 | GET | `/api/v1/agents/identity/status` | Identity job status |
+| 53 | POST | `/api/v1/agents/identity/suggest` | Identity suggestions |
+| 54 | POST | `/api/v1/agents/suggest/merge` | Suggest identity merge |
+| 55 | POST | `/api/v1/agents/suggest/clustering` | Suggest re-clustering |
+
+---
+
+## Summary
+
+| Module | Routes | File |
+|--------|--------|------|
+| Core | 21 | `server.rs` |
+| File/Identity | 12 | `identity_api.rs` |
+| Binding | 3 | `identity_binding.rs` |
+| Faces | 1 | `identities.rs` |
+| Search | 3 | `search.rs`, `universal_search.rs` |
+| Trace | 2 | `trace_agent_api.rs` |
+| Media | 4 | `media_api.rs` |
+| Agents | 9 | `agent_api.rs`, `five_w1h_agent_api.rs`, `identity_agent_api.rs` |
+| **Total** | **55** | |