# Project N.O.M.A.D. API Endpoints: Complete Guide to Service Integration

> Explore Project N.O.M.A.D. API endpoints for seamless service integration. Access AI chat, system management, ZIM libraries, maps & benchmarking programmatically.

- Repository: [Crosstalk Solutions/project-nomad](https://github.com/Crosstalk-Solutions/project-nomad)
- Tags: api-reference
- Published: 2026-03-16

---

**Project N.O.M.A.D. exposes its core functionality through RESTful HTTP routes defined in [`admin/start/routes.ts`](https://github.com/Crosstalk-Solutions/project-nomad/blob/main/admin/start/routes.ts), providing programmatic access to AI chat, system management, ZIM libraries, maps, and benchmarking services.**

All API routes for the Crosstalk-Solutions/project-nomad repository are registered using the AdonisJS router framework. The routes are organized by functional service domains and prefixed with `/api/` for programmatic endpoints, while UI-specific routes render Inertia.js views for the administrative interface.

## Core UI and Health Check Endpoints

The application exposes several browser-facing routes for the administrative interface alongside a critical health probe for monitoring.

### Administrative Interface Routes

According to lines **27-32** of [`admin/start/routes.ts`](https://github.com/Crosstalk-Solutions/project-nomad/blob/main/admin/start/routes.ts), the following `GET` endpoints serve the Inertia-based UI:

- `/` – Renders the main home page dashboard
- `/home` – Alternate entry point for the home interface
- `/about` – Displays the About page
- `/chat` – Loads the chat interface UI
- `/maps` – Serves the maps visualization UI
- `/knowledge-base` – Legacy redirect to `/chat` with `knowledge_base=true` parameter

### Health Check Endpoint

Every Project N.O.M.A.D. deployment exposes a simple status probe at:

- **`GET /api/health`** – Returns `{ status: "ok" }` for load balancers and monitoring systems

*Source:* lines **97-99** in [`admin/start/routes.ts`](https://github.com/Crosstalk-Solutions/project-nomad/blob/main/admin/start/routes.ts)

## Easy-Setup Service Endpoints

The quick-start wizard exposes both UI and API endpoints for initial configuration, defined at lines **34-38**:

**UI Routes:**
- `GET /easy-setup` – Displays the setup wizard interface
- `GET /easy-setup/complete` – Renders the post-setup completion page

**API Routes:**
- `GET /api/easy-setup/curated-categories` – Retrieves curated collection categories for initial content selection
- `POST /api/manifests/refresh` – Triggers a manual refresh of manifest files

## Content Update Service Endpoints

Manage offline content collections through the content-update API (lines **40-44**):

- **`POST /api/content-updates/check`** – Verifies whether new collection updates are available for download
- **`POST /api/content-updates/apply`** – Applies a single pending update to the local system
- **`POST /api/content-updates/apply-all`** – Executes all pending content updates sequentially

## Settings Management Endpoints

Configuration management uses a hybrid approach with UI routes and a RESTful settings API defined at lines **48-58**.

**Configuration UI Routes (`GET`):**
- `/settings/system` – System-level configuration panel
- `/settings/apps` – Installed applications management
- `/settings/legal` – Legal information display
- `/settings/maps` – Map service configuration
- `/settings/models` – AI model parameters
- `/settings/update` – System update interface
- `/settings/zim` – ZIM library management
- `/settings/zim/remote-explorer` – Remote ZIM file browser
- `/settings/benchmark` – Performance testing panel

**Settings API:**
- `GET /settings` – Retrieves a specific configuration value
- `PATCH /settings` – Updates a configuration parameter

## Documentation Service Endpoints

The built-in documentation system provides programmatic access to help content (lines **86-89**):

- **`GET /api/docs/list`** – Returns an array of available documentation pages
- **`GET /docs/:slug`** – Renders a specific documentation page via Inertia, with fallback redirect to `/docs/home`

## Maps Service Endpoints

Geographic data management routes are defined at lines **72-80**, supporting offline map operations:

- **`GET /api/maps/regions`** – Lists available geographic regions
- **`GET /api/maps/styles`** – Returns available map rendering styles
- **`GET /api/maps/curated-collections`** – Lists curated map content collections
- **`POST /api/maps/fetch-latest-collections`** – Pulls updated collection metadata from remote sources
- **`POST /api/maps/download-base-assets`** – Downloads core map rendering assets
- **`POST /api/maps/download-remote`** – Initiates download of a remote map file
- **`POST /api/maps/download-remote-preflight`** – Performs pre-flight validation before remote downloads
- **`POST /api/maps/download-collection`** – Downloads a specific map collection bundle
- **`DELETE /api/maps/:filename`** – Removes a cached map file from local storage

## Download Management Endpoints

Monitor asynchronous download operations through the jobs API (lines **92-95**):

- **`GET /api/downloads/jobs`** – Lists all active and completed download jobs
- **`GET /api/downloads/jobs/:filetype`** – Filters download jobs by specific file type

## Ollama AI Service Endpoints

Integration with local Ollama instances for large language model operations is handled at lines **103-108**:

- **`POST /api/ollama/chat`** – Sends chat completion requests to the configured Ollama model
- **`GET /api/ollama/models`** – Lists all models available in the local Ollama instance
- **`POST /api/ollama/models`** – Triggers download of a new model from the Ollama repository
- **`DELETE /api/ollama/models`** – Removes a model from the host system to free disk space
- **`GET /api/ollama/installed-models`** – Returns the subset of models currently cached locally

## Chat Session Management Endpoints

Conversational AI state is managed through the session API defined across lines **13-21** and **23-24**:

- **`GET /api/chat/sessions/`** – Retrieves all chat sessions with metadata
- **`POST /api/chat/sessions/`** – Creates a new chat session entity
- **`DELETE /api/chat/sessions/all`** – Purges all chat sessions from the database
- **`GET /api/chat/sessions/:id`** – Fetches a specific session by UUID
- **`PUT /api/chat/sessions/:id`** – Updates session metadata (title, archived status)
- **`DELETE /api/chat/sessions/:id`** – Removes a specific session and its message history
- **`POST /api/chat/sessions/:id/messages`** – Appends a new message to the conversation thread
- **`GET /api/chat/suggestions`** – Retrieves AI-generated prompt suggestions for the current context

## RAG Service Endpoints

Retrieval-Augmented Generation document indexing operates through the `/api/rag` namespace (lines **27-33**):

- **`POST /api/rag/upload`** – Accepts document uploads for vector indexing
- **`GET /api/rag/files`** – Lists all files currently stored in the RAG vector store
- **`DELETE /api/rag/files`** – Removes a document from the index and storage
- **`GET /api/rag/active-jobs`** – Returns ongoing indexing or embedding jobs
- **`GET /api/rag/job-status`** – Queries the status of a specific background job
- **`POST /api/rag/sync`** – Scans the filesystem and synchronizes the vector index with detected changes

## System Administration Endpoints

Comprehensive system control routes are defined at lines **38-55**, covering services, updates, and configuration:

**System Information:**
- `GET /api/system/info` – General hardware and software information
- `GET /api/system/internet-status` – Connectivity validation
- `GET /api/system/latest-version` – Current and available Project N.O.M.A.D. versions

**Service Management:**
- `GET /api/system/services` – Lists all managed system services
- `POST /api/system/services/affect` – Enables or disables a service
- `POST /api/system/services/install` – Installs a new service package
- `POST /api/system/services/force-reinstall` – Force reinstalls an existing service
- `POST /api/system/services/check-updates` – Checks for available service updates
- `GET /api/system/services/:name/available-versions` – Lists available versions for a specific service
- `POST /api/system/services/update` – Updates a service to a specific version

**System Updates:**
- `POST /api/system/update` – Initiates a system update process
- `GET /api/system/update/status` – Polls update progress
- `GET /api/system/update/logs` – Retrieves update operation logs
- `POST /api/system/subscribe-release-notes` – Registers for release notification emails

**Configuration:**
- `GET /api/system/settings` – Reads raw configuration values
- `PATCH /api/system/settings` – Modifies system configuration parameters

## ZIM Library Service Endpoints

Offline Wikipedia and ZIM file management routes appear at lines **59-68**:

- **`GET /api/zim/list`** – Lists locally stored ZIM archive files
- **`GET /api/zim/list-remote`** – Lists available remote ZIM collections
- **`GET /api/zim/curated-categories`** – Returns curated ZIM content categories
- **`POST /api/zim/download-remote`** – Downloads a specific remote ZIM file
- **`POST /api/zim/download-category-tier`** – Downloads a tiered category of ZIM content
- **`GET /api/zim/wikipedia`** – Returns current Wikipedia ZIM installation state
- **`POST /api/zim/wikipedia/select`** – Selects and activates a specific Wikipedia ZIM version
- **`DELETE /api/zim/:filename`** – Deletes a ZIM file from local storage

## Benchmark Service Endpoints

Performance testing and hardware validation endpoints are defined at lines **73-84**:

- **`POST /api/benchmark/run`** – Executes the complete benchmark suite
- **`POST /api/benchmark/run/system`** – Benchmarks CPU, memory, and storage subsystems
- **`POST /api/benchmark/run/ai`** – Tests AI model inference performance
- **`GET /api/benchmark/results`** – Retrieves historical benchmark results
- **`GET /api/benchmark/results/latest`** – Fetches the most recent benchmark run
- **`GET /api/benchmark/results/:id`** – Returns a specific benchmark result by ID
- **`POST /api/benchmark/submit`** – Submits benchmark data to external aggregators
- **`POST /api/benchmark/builder-tag`** – Updates metadata tags for benchmark builds
- **`GET /api/benchmark/comparison`** – Compares multiple benchmark runs
- **`GET /api/benchmark/status`** – Checks if a benchmark is currently running
- **`GET /api/benchmark/settings`** – Retrieves benchmark configuration
- **`POST /api/benchmark/settings`** – Updates benchmark parameters

## How to Call Project N.O.M.A.D. API Endpoints

All endpoints accept JSON payloads and return JSON responses. The following JavaScript examples demonstrate common operations against a local instance running on port `3333`:

```javascript
const BASE_URL = 'http://localhost:3333';

// Health check
async function healthCheck() {
  const resp = await fetch(`${BASE_URL}/api/health`);
  return await resp.json(); // → { status: "ok" }
}

// List available Ollama models
async function listOllamaModels() {
  const resp = await fetch(`${BASE_URL}/api/ollama/models`);
  return await resp.json();
}

// Create a new chat session
async function createChatSession(title) {
  const resp = await fetch(`${BASE_URL}/api/chat/sessions/`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ title })
  });
  return await resp.json();
}

// Add a message to a session
async function addMessage(sessionId, content) {
  await fetch(`${BASE_URL}/api/chat/sessions/${sessionId}/messages`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ role: 'user', content })
  });
}

// Trigger a system update check
async function checkSystemVersion() {
  const resp = await fetch(`${BASE_URL}/api/system/latest-version`);
  return await resp.json();
}

// Download a remote ZIM file
async function downloadZimRemote(url) {
  await fetch(`${BASE_URL}/api/zim/download-remote`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ url })
  });
}

```

## Summary

- **Central Routing**: All Project N.O.M.A.D. API endpoints are defined in [`admin/start/routes.ts`](https://github.com/Crosstalk-Solutions/project-nomad/blob/main/admin/start/routes.ts) using the AdonisJS router framework.
- **Service Organization**: Endpoints are grouped into 13 functional domains including AI (Ollama), chat sessions, RAG, system administration, ZIM libraries, maps, and benchmarking.
- **RESTful Patterns**: The API uses standard HTTP methods (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) with JSON payloads for state transfer.
- **Real-time Support**: While REST endpoints handle most operations, `transmit.registerRoutes()` (line 25) enables WebSocket channels for real-time UI updates.
- **Controller Architecture**: Routes invoke controllers located in `admin/controllers/` (e.g., `ChatsController`, `OllamaController`) to handle business logic.

## Frequently Asked Questions

### What authentication is required for the Project N.O.M.A.D. API?

The provided route definitions in [`admin/start/routes.ts`](https://github.com/Crosstalk-Solutions/project-nomad/blob/main/admin/start/routes.ts) do not explicitly show authentication middleware on individual routes. According to the AdonisJS pattern used in the codebase, authentication is likely handled globally in the kernel or applied via route groups. Check [`admin/start/kernel.ts`](https://github.com/Crosstalk-Solutions/project-nomad/blob/main/admin/start/kernel.ts) for registered middleware that may enforce session or token-based authentication before accessing sensitive endpoints like `/api/system/update` or `/api/ollama/models`.

### Can I use the Project N.O.M.A.D. API to manage offline content programmatically?

Yes. The API provides comprehensive endpoints for offline content management. Use `POST /api/content-updates/check` to verify available updates, `POST /api/maps/fetch-latest-collections` to refresh map metadata, and `POST /api/zim/download-remote` to download Wikipedia archives. These endpoints allow full automation of content synchronization without using the web interface.

### How do I monitor long-running operations like model downloads or system updates?

Monitor asynchronous operations using the status endpoints specific to each service. For system updates, poll `GET /api/system/update/status` after initiating `POST /api/system/update`. For downloads, use `GET /api/downloads/jobs` to track job progress. The RAG service provides `GET /api/rag/active-jobs` and `GET /api/rag/job-status` for document indexing operations.

### What is the difference between `/settings` and `/api/system/settings` endpoints?

The `/settings` routes (lines 48-58) primarily serve the administrative UI via Inertia.js and handle high-level application preferences. In contrast, `/api/system/settings` (lines 38-55) provides low-level access to raw configuration values for the underlying system services. Use `/api/system/settings` for programmatic configuration management and `/settings` for human-readable configuration interfaces.