diff --git a/admin/docs/api-reference.md b/admin/docs/api-reference.md new file mode 100644 index 0000000..5cf126f --- /dev/null +++ b/admin/docs/api-reference.md @@ -0,0 +1,200 @@ +# API Reference + +N.O.M.A.D. exposes a REST API for all operations. All endpoints are under `/api/` and return JSON. + +--- + +## Conventions + +**Base URL:** `http:///api` + +**Responses:** +- Success responses include `{ "success": true }` and an HTTP 2xx status +- Error responses return the appropriate HTTP status (400, 404, 409, 500) with an error message +- Long-running operations (downloads, benchmarks, embeddings) return 201 or 202 with a job/benchmark ID for polling + +**Async pattern:** Submit a job → receive an ID → poll a status endpoint until complete. + +--- + +## Health + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/api/health` | Returns `{ "status": "ok" }` | + +--- + +## System + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/api/system/info` | CPU, memory, disk, and platform info | +| GET | `/api/system/internet-status` | Check internet connectivity | +| GET | `/api/system/debug-info` | Detailed debug information | +| GET | `/api/system/latest-version` | Check for the latest N.O.M.A.D. version | +| POST | `/api/system/update` | Trigger a system update | +| GET | `/api/system/update/status` | Get update progress | +| GET | `/api/system/update/logs` | Get update operation logs | +| GET | `/api/system/settings` | Get a setting value (query param: `key`) | +| PATCH | `/api/system/settings` | Update a setting (`{ key, value }`) | +| POST | `/api/system/subscribe-release-notes` | Subscribe an email to release notes | + +### Services + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/api/system/services` | List all services with status | +| POST | `/api/system/services/install` | Install a service | +| POST | `/api/system/services/force-reinstall` | Force reinstall a service | +| POST | `/api/system/services/affect` | Start, stop, or restart a service (body: `{ name, action }`) | +| POST | `/api/system/services/check-updates` | Check for available service updates | +| POST | `/api/system/services/update` | Update a service to a specific version | +| GET | `/api/system/services/:name/available-versions` | List available versions for a service | + +--- + +## AI Chat + +### Models + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/api/ollama/models` | List available models (supports filtering, sorting, pagination) | +| GET | `/api/ollama/installed-models` | List locally installed models | +| POST | `/api/ollama/models` | Download a model (async, returns job) | +| DELETE | `/api/ollama/models` | Delete an installed model | + +### Chat + +| Method | Path | Description | +|--------|------|-------------| +| POST | `/api/ollama/chat` | Send a chat message. Supports streaming (SSE) and RAG context injection. Body: `{ model, messages, stream?, useRag? }` | +| GET | `/api/chat/suggestions` | Get suggested chat prompts | + +### Remote Ollama + +| Method | Path | Description | +|--------|------|-------------| +| POST | `/api/ollama/configure-remote` | Configure a remote Ollama or LM Studio instance | +| GET | `/api/ollama/remote-status` | Check remote Ollama connection status | + +### Chat Sessions + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/api/chat/sessions` | List all chat sessions | +| POST | `/api/chat/sessions` | Create a new session | +| GET | `/api/chat/sessions/:id` | Get a session with its messages | +| PUT | `/api/chat/sessions/:id` | Update session metadata (title, etc.) | +| DELETE | `/api/chat/sessions/:id` | Delete a session | +| DELETE | `/api/chat/sessions/all` | Delete all sessions | +| POST | `/api/chat/sessions/:id/messages` | Add a message to a session | + +**Streaming:** The `/api/ollama/chat` endpoint supports Server-Sent Events (SSE) when `stream: true` is passed. Connect using `EventSource` or `fetch` with a streaming reader. + +--- + +## Knowledge Base (RAG) + +Upload documents to enable AI-powered retrieval during chat. + +| Method | Path | Description | +|--------|------|-------------| +| POST | `/api/rag/upload` | Upload a file for embedding (async, 202 response) | +| GET | `/api/rag/files` | List stored RAG files | +| DELETE | `/api/rag/files` | Delete a file (query param: `source`) | +| GET | `/api/rag/active-jobs` | List active embedding jobs | +| GET | `/api/rag/job-status` | Get status for a specific file embedding job | +| GET | `/api/rag/failed-jobs` | List failed embedding jobs | +| DELETE | `/api/rag/failed-jobs` | Clean up failed jobs and delete associated files | +| POST | `/api/rag/sync` | Scan storage and sync database with filesystem | + +--- + +## ZIM Files (Offline Content) + +ZIM files provide offline Wikipedia, books, and other content via Kiwix. + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/api/zim/list` | List locally stored ZIM files | +| GET | `/api/zim/list-remote` | List remote ZIM files (paginated, supports search) | +| GET | `/api/zim/curated-categories` | List curated categories with Essential/Standard/Comprehensive tiers | +| POST | `/api/zim/download-remote` | Download a remote ZIM file (async) | +| POST | `/api/zim/download-category-tier` | Download a full category tier | +| DELETE | `/api/zim/:filename` | Delete a local ZIM file | + +### Wikipedia + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/api/zim/wikipedia` | Get current Wikipedia selection state | +| POST | `/api/zim/wikipedia/select` | Select a Wikipedia edition and tier | + +--- + +## Maps + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/api/maps/regions` | List available map regions | +| GET | `/api/maps/styles` | Get map styles JSON | +| GET | `/api/maps/curated-collections` | List curated map collections | +| POST | `/api/maps/fetch-latest-collections` | Fetch latest collection metadata from source | +| POST | `/api/maps/download-base-assets` | Download base map assets | +| POST | `/api/maps/download-remote` | Download a remote map file (async) | +| POST | `/api/maps/download-remote-preflight` | Check download size/info before starting | +| POST | `/api/maps/download-collection` | Download an entire collection by slug (async) | +| DELETE | `/api/maps/:filename` | Delete a local map file | + +--- + +## Downloads + +Manage background download jobs for maps, ZIM files, and models. + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/api/downloads/jobs` | List all download jobs | +| GET | `/api/downloads/jobs/:filetype` | List jobs filtered by type (`zim`, `map`, etc.) | +| DELETE | `/api/downloads/jobs/:jobId` | Cancel and remove a download job | + +--- + +## Benchmarks + +| Method | Path | Description | +|--------|------|-------------| +| POST | `/api/benchmark/run` | Run a benchmark (`full`, `system`, or `ai`; can be async) | +| POST | `/api/benchmark/run/system` | Run system-only benchmark | +| POST | `/api/benchmark/run/ai` | Run AI-only benchmark | +| GET | `/api/benchmark/status` | Get current benchmark status (`idle` or `running`) | +| GET | `/api/benchmark/results` | Get all benchmark results | +| GET | `/api/benchmark/results/latest` | Get the most recent result | +| GET | `/api/benchmark/results/:id` | Get a specific result | +| POST | `/api/benchmark/submit` | Submit a result to the central repository | +| POST | `/api/benchmark/builder-tag` | Update builder tag metadata for a result | +| GET | `/api/benchmark/comparison` | Get comparison stats from the repository | +| GET | `/api/benchmark/settings` | Get benchmark settings | +| POST | `/api/benchmark/settings` | Update benchmark settings | + +--- + +## Easy Setup & Content Updates + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/api/easy-setup/curated-categories` | List curated content categories for setup wizard | +| POST | `/api/manifests/refresh` | Refresh manifest caches (`zim_categories`, `maps`, `wikipedia`) | +| POST | `/api/content-updates/check` | Check for available collection updates | +| POST | `/api/content-updates/apply` | Apply a single content update | +| POST | `/api/content-updates/apply-all` | Apply multiple content updates | + +--- + +## Documentation + +| Method | Path | Description | +|--------|------|-------------| +| GET | `/api/docs/list` | List all available documentation files |