REST API Endpoints Reference
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The KnowledgeVault project provides a robust REST API layer built with FastAPI, facilitating document management, RAG (Retrieval-Augmented Generation) chat interactions, and structured knowledge management through Wiki and KMS (Knowledge Management System) modules. The API serves as the primary interface for the React-based frontend and external integrations, supporting complex workflows such as semantic document indexing, multi-namespace evidence citation, and asynchronous knowledge compilation.
The API is architected with security and multi-tenancy as core principles, utilizing JWT-based authentication with httpOnly refresh cookies and CSRF protection for all mutating requests. Most endpoints are scoped to specific "Vaults," ensuring that data access and manipulation follow defined organizational and user permissions.
Sources: README.md:144-156, frontend/src/lib/api.ts:50-100, backend/app/api/routes/wiki.py:12-25
Authentication and Security
Authentication is handled via a dual-token system: a short-lived JWT access token passed in the Authorization header and a long-lived refresh token stored in an httpOnly cookie. This structure prevents XSS-based token theft while allowing seamless session persistence.
Security Mechanisms
- CSRF Protection: All mutating methods (POST, PUT, PATCH, DELETE) require a valid CSRF token. The frontend intercepts these requests to attach the
X-CSRF-Tokenheader. - Vault Scoping: Endpoints frequently require a
vault_idparameter to enforce isolation between different knowledge silos. - Role-Based Access Control (RBAC): Users are assigned roles (Superadmin, Admin, Member, Viewer) that govern access to sensitive administrative routes and vault operations.
Sources: frontend/src/lib/api.ts:74-120, README.md:112-117, backend/app/api/routes/wiki.py:72-85
Auth Flow Diagram
The following diagram illustrates the token refresh and authenticated request flow utilized by the API clients.
Knowledge Base (Wiki) Endpoints
The Wiki subsystem allows for the creation and management of structured claims, entities, and pages. It supports advanced features like version history, backlink tracking, and automated linting for contradictory information.
Wiki Page Management
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/wiki/pages | List wiki pages with filtering by page_type, status, or search. |
| POST | /api/wiki/pages | Create a new wiki page (Requires vault_id, title, page_type). |
| GET | /api/wiki/pages/{page_id} | Retrieve full details of a specific wiki page. |
| PUT | /api/wiki/pages/{page_id} | Update an existing wiki page. Supports optimistic locking via expected_version. |
| DELETE | /api/wiki/pages/{page_id} | Permanently remove a wiki page. |
Sources: backend/app/api/routes/wiki.py:126-224, frontend/src/lib/api.ts:1330-1360
Wiki Knowledge Compilation
Wiki knowledge is often generated or verified via asynchronous jobs. The API provides endpoints to manage these jobs and monitor their status.
Chat and RAG Endpoints
The chat system is the primary interface for RAG operations. It supports both standard JSON responses and Server-Sent Events (SSE) for real-time streaming of assistant answers and evidence citations.
Chat Operations
| Endpoint | Method | Purpose |
|---|---|---|
/api/chat/stream | POST | Stream assistant responses. Emits tokens and complex metadata (sources, wiki_used, kms_used). |
/api/chat/sessions | POST | Initialize a new persistent chat session. |
/api/chat/sessions/{id}/messages | POST | Append a message to an existing session. |
/api/chat/sessions/{id}/fork | POST | Branch a conversation from a specific message index. |
Sources: frontend/src/lib/api.ts:1000-1150, README.md:730-745, specs/wire-wiki-chat/SPEC.md:120-135
Evidence Namespaces
The API utilizes distinct citation namespaces to inform the frontend of evidence provenance:
[S#]: Document Sources (Vector Retrieval)[M#]: User Memories (Durable context)[W#]: Wiki Claims (Structured domain knowledge)[K#]: KMS Entries (Curated documentation)
Sources: specs/wire-wiki-chat/SPEC.md:135-145, specs/kms-content-search-rag/SPEC.md:70-85
Document Management
Document endpoints handle the lifecycle of files from upload to semantic indexing. Recent updates introduced Full-Text Search (FTS) for document content, allowing searches beyond metadata.
| Method | Endpoint | Description |
|---|---|---|
| POST | /api/documents/upload | Upload files for processing. Handles multipart/form-data. |
| GET | /api/documents | List documents with FTS support for search parameter. |
| GET | /api/documents/{id}/status | Check processing phase (e.g., parsing, embedding, indexing). |
| POST | /api/documents/scan | Trigger the file watcher to detect new files in the vault upload directory. |
Sources: frontend/src/lib/api.ts:850-930, specs/kms-content-search-rag/SPEC.md:40-60, README.md:750-765
Summary
The KnowledgeVault API is a comprehensive suite of endpoints designed to bridge the gap between raw document storage and AI-powered knowledge retrieval. By segmenting knowledge into distinct namespaces (Wiki, KMS, Sources, Memories) and providing robust lifecycle management for each, the API enables sophisticated RAG workflows that prioritize evidence provenance and structural accuracy. Integrated security measures and asynchronous job handling ensure the system remains performant and secure in multi-user environments.
Sources: README.md:15-40, specs/wire-wiki-chat/SPEC.md:10-25