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

Project N.O.M.A.D. exposes its core functionality through RESTful HTTP routes defined in 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, 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

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:

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 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}