Base URL
config/main.yaml under server.backend_port. Interactive API docs (Swagger UI) are available at:
Route structure
| Prefix | Description |
|---|---|
/api/v1/ | All versioned API routes |
/api/outputs/ | Static files served from data/user/ |
Authentication
No authentication is required for self-hosted deployments. All endpoints are open by default. For production use, add your own authentication middleware before exposing the API publicly.CORS
The server currently allows all origins:src/api/main.py to specify your frontend origin.
Transport protocols
The API uses both HTTP and WebSocket:- REST (HTTP): Used for CRUD operations — knowledge base management, notebook management, co-writer operations, and session state retrieval.
- WebSocket: Used for long-running AI tasks that stream progress and results — solving, research, question generation, idea generation, and guided learning.
WebSocket pattern
All WebSocket endpoints follow the same pattern:Receive streaming messages
The server streams typed JSON messages as the task progresses. Message types include
task_id, status, log, agent_status, token_stats, progress, and result.WebSocket message types
type | When sent | Description |
|---|---|---|
task_id | After connection | Unique ID for this task run |
session | After connection (solve) | Session ID for conversation history |
status | At start and key stages | Human-readable status string |
log | During execution | Log lines from the agent |
agent_status | During execution | Per-agent status updates |
token_stats | During and after execution | LLM token usage and cost |
progress | During execution | Structured progress object |
result | On completion | Final output |
error | On failure | Error message string |
complete | On completion (some endpoints) | Signals the stream is done |
Static outputs
Generated artifacts (images, PDFs, Markdown files) are served at:data/user/solve/solve_20250101_120000/artifacts/diagram.png on the server.
Endpoints
Solve
WebSocket AI problem solver with streaming agent logs and session history.
Research
WebSocket deep research pipeline with topic optimization.
Knowledge
REST endpoints for creating and managing knowledge bases and document uploads.
Question
WebSocket question generation from knowledge base content.
Notebook
REST endpoints for creating notebooks and saving learning records.
Co-writer
REST endpoints for AI-assisted text editing, annotation, and TTS narration.
Guide
REST and WebSocket endpoints for guided learning sessions.
IdeaGen
WebSocket research idea generation from notebook content.