Next.js API Routes
Relevant source files
The following files were used as context for generating this wiki page:
Next.js API Routes in this project serve as the primary bridge between the frontend user interface and the backend services, including the local database and external AI provider harnesses. These routes handle critical operations such as managing AI provider credentials, fetching available model lists, persisting user settings, and retrieving chat history.
The API architecture is designed to support a desktop-centric environment where the web frontend interacts with services orchestrated by an Electron shell or a local Node.js server. These routes facilitate the management of state for the "Nudge" AI tutor, ensuring that sensitive data like API keys are handled securely via specific endpoints.
Sources: apps/web/src/lib/api.ts, CONTRIBUTING.md:14-23, apps/web/next.config.ts:40-45
Core API Structure and Connectivity
The API routes are consumed through a centralized api client utility that abstracts the standard fetch calls. This client handles JSON parsing and error management for various system modules.
API Client Implementation
The client uses a helper function j<T> to process responses, ensuring that non-OK status codes throw descriptive errors derived from the response body.
async function j<T>(res: Response): Promise<T> {
if (!res.ok) throw new Error((await res.json().catch(() => ({})))?.error ?? res.statusText);
return res.json() as Promise<T>;
}
Sources: apps/web/src/lib/api.ts:20-23
Request Flow Overview
The following diagram illustrates the flow from a UI component through the API client to the backend routes.
Sources: apps/web/src/lib/api.ts, CONTRIBUTING.md:14-23
Endpoint Specifications
The system defines several categories of endpoints to manage the application's lifecycle and AI interactions.
Provider and Model Management
These endpoints manage the connection to AI services like OpenAI or Anthropic. They allow for setting API keys and listing available models.
| Endpoint | Method | Description |
|---|---|---|
/api/providers | GET | Returns a list of supported AI providers and their current status (e.g., if a key is set). |
/api/providers | POST | Upserts an API key for a specific provider kind. |
/api/providers/:id | PATCH | Updates or clears the API key for a specific provider instance. |
/api/models | GET | Fetches models from a specific provider, passed as a query parameter. |
Sources: apps/web/src/lib/api.ts:26-34, apps/web/src/components/settings/ModelsSettings.tsx:44-58
Settings and State
The settings API persists application-wide configurations, such as the preferred model for live voice interactions and vision tasks.
| Field | Type | Description |
|---|---|---|
liveModel | string | The ID of the primary model used for voice/chat. |
liveProviderId | string | The ID of the provider for the live model. |
liveEffort | string | The reasoning effort level (e.g., "auto", "low", "high"). |
visionModel | string | Optional dedicated model for processing image frames. |
Sources: apps/web/src/lib/api.ts:10-18, apps/web/src/components/settings/ModelsSettings.tsx:115-135
Chat History and Persistence
Routes under /api/chats handle the retrieval and deletion of conversation history.
Security and Integration
Content Security Policy (CSP)
Next.js API routes and the overall web application are governed by a strict CSP defined in the Next.js configuration. This is particularly important because the app renders model-authored HTML and connects to external model hosts.
- connect-src: Allows connections to
self, the Live WebSocket, and specific model hosts (huggingface.co,jsdelivr.net). - script-src: Allows
wasm-unsafe-evalto support WebAssembly runtimes like ONNX used for on-device AI.
Sources: apps/web/next.config.ts:11-35
Workspace Dependencies
The API routes rely on internal workspace packages to perform their logic:
@openlive/db: Used for JSON-file storage of keys and settings.@openlive/harness: Used for model adapters and provider registries.
Sources: apps/web/package.json:20-22, CONTRIBUTING.md:14-23
Summary
The Next.js API routes provide a structured interface for the Nudge application to interact with its local persistence layer and external AI capabilities. By centralizing logic in routes and abstracting access through a TypeScript-typed API client, the project ensures consistent data handling across the settings, chat, and provider management modules.