From 76c4d471124b281537936f05573ace5da66d0a16 Mon Sep 17 00:00:00 2001 From: Warren Date: Fri, 8 May 2026 02:41:43 +0800 Subject: [PATCH] docs: complete API dictionary v1.0.0 (55 endpoints) --- docs_v1.0/API_V1.0.0/API_DICTIONARY_V1.0.0.md | 122 ++++++++++++++++++ 1 file changed, 122 insertions(+) create mode 100644 docs_v1.0/API_V1.0.0/API_DICTIONARY_V1.0.0.md diff --git a/docs_v1.0/API_V1.0.0/API_DICTIONARY_V1.0.0.md b/docs_v1.0/API_V1.0.0/API_DICTIONARY_V1.0.0.md new file mode 100644 index 0000000..5db2356 --- /dev/null +++ b/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** | |