claude-os/docs/API_REFERENCE.md

Claude OS API Reference

Base URL: http://localhost:8051

Complete reference for all Claude OS MCP Server API endpoints.

---

Table of Contents

1. Knowledge Base Operations
2. Hybrid Indexing
3. Project Management
4. Hooks System
5. File Watcher
6. Authentication
7. Utilities
8. Health Check

---

Knowledge Base Operations

Create Knowledge Base

POST /api/kb
Content-Type: application/json

{
  "name": "my-project-docs",
  "kb_type": "generic",
  "description": "Project documentation"
}

KB Types:

• generic - General purpose
• code - Code-specific
• documentation - Documentation files
• agent-os - Agent-OS integration

Response:

{
  "success": true,
  "name": "my-project-docs",
  "kb_type": "generic",
  "description": "Project documentation"
}

---

List Knowledge Bases

GET /api/kb

Response:

{
  "knowledge_bases": [
    {
      "id": 1,
      "name": "my-project-docs",
      "slug": "my-project-docs",
      "metadata": {
        "kb_type": "generic",
        "description": "Project documentation",
        "created_at": "2025-10-31 12:00:00"
      }
    }
  ]
}

---

Get Knowledge Base Stats

GET /api/kb/{kb_name}/stats

Response:

{
  "name": "my-project-docs",
  "document_count": 42,
  "total_size_bytes": 1048576,
  "created_at": "2025-10-31 12:00:00"
}

---

List Documents in Knowledge Base

GET /api/kb/{kb_name}/documents

Response:

{
  "kb_name": "my-project-docs",
  "documents": [
    {
      "id": "doc_123",
      "filename": "README.md",
      "size_bytes": 2048,
      "chunks": 3,
      "created_at": "2025-10-31 12:00:00"
    }
  ]
}

---

Query Knowledge Base

POST /api/kb/{kb_name}/chat
Content-Type: application/json

{
  "message": "What is the authentication flow?",
  "context_size": 5
}

Response:

{
  "response": "The authentication flow uses JWT tokens...",
  "sources": [
    {
      "filename": "auth.md",
      "chunk_id": "chunk_42",
      "similarity": 0.87
    }
  ],
  "context_used": 3
}

---

Upload Document

POST /api/kb/{kb_name}/upload
Content-Type: multipart/form-data

file=@/path/to/document.pdf

Response:

{
  "success": true,
  "filename": "document.pdf",
  "kb_name": "my-project-docs",
  "chunks_created": 15
}

---

Import Directory

POST /api/kb/{kb_name}/import
Content-Type: application/json

{
  "directory_path": "/path/to/docs",
  "file_types": [".md", ".txt", ".pdf"]
}

Response:

{
  "success": true,
  "files_processed": 42,
  "files_successful": 40,
  "files_failed": 2,
  "total_chunks": 350
}

---

Delete Document

DELETE /api/kb/{kb_name}/documents/{filename}

Response:

{
  "success": true,
  "message": "Document deleted successfully"
}

---

Delete Knowledge Base

DELETE /api/kb/{kb_name}

Response:

{
  "success": true,
  "message": "Knowledge base deleted successfully"
}

---

Hybrid Indexing (NEW!)

Phase 1: Structural Indexing (Tree-Sitter)

POST /api/kb/{kb_name}/index-structural
Content-Type: application/json

{
  "project_path": "/Users/username/Projects/myproject",
  "token_budget": 2048,
  "cache_path": ".claude-os/tree_sitter_cache.db"
}

What it does:

• Parses code with tree-sitter (no LLM calls)
• Extracts all symbols (classes, functions, methods)
• Builds dependency graph
• Computes PageRank importance scores
• Stores as JSON (no embeddings)

Speed: ~30 seconds for 10,000 files

Response:

{
  "success": true,
  "kb_name": "myproject-code_structure",
  "total_files": 3117,
  "total_symbols": 36591,
  "time_taken_seconds": 3.04,
  "repo_map_preview": "app/models/user.rb:\n  1: class User...",
  "message": "Structural index created: 36591 symbols in 3117 files"
}

---

Phase 2: Selective Semantic Indexing (Embeddings)

POST /api/kb/{kb_name}/index-semantic
Content-Type: application/json

{
  "project_path": "/Users/username/Projects/myproject",
  "selective": true,
  "code_structure_kb": "myproject-code_structure"
}

What it does (Selective Mode):

• Gets top 20% most important files from structural index (by PageRank)
• Includes all documentation files
• Generates embeddings only for selected files
• 80% reduction in embedding time and storage

What it does (Full Mode):

{
  "selective": false
}

• Generates embeddings for ALL files
• Slower but more comprehensive

Response (Selective):

{
  "success": true,
  "kb_name": "myproject-project_index",
  "mode": "selective",
  "files_selected": 623,
  "files_indexed": 620,
  "time_taken_seconds": 1200,
  "message": "Selective semantic indexing complete: 620/623 files indexed"
}

Response (Full):

{
  "success": true,
  "kb_name": "myproject-project_index",
  "mode": "full",
  "total_files": 3117,
  "successful": 3100,
  "time_taken_seconds": 10800,
  "message": "Full semantic indexing complete: 3100 files indexed"
}

---

Get Repo Map

GET /api/kb/{kb_name}/repo-map?token_budget=1024&project_path=/path/to/project

What it does:

• Generates compact code structure map
• Fits within specified token budget
• Shows most important symbols first (PageRank-ranked)
• Perfect for including in Claude's prompt context

Response:

{
  "success": true,
  "repo_map": "app/models/user.rb:\n  1: class User < ApplicationRecord\n  15: def authenticate...",
  "token_count": 820,
  "total_symbols": 36591,
  "total_files": 3117
}

---

Project Management

List Projects

GET /api/projects

Response:

{
  "projects": [
    {
      "id": 1,
      "name": "My Project",
      "path": "/Users/username/Projects/myproject",
      "created_at": "2025-10-31 12:00:00",
      "mcps": {
        "memories": "myproject-project_memories",
        "index": "myproject-project_index",
        "profile": "myproject-project_profile",
        "docs": "myproject-knowledge_docs",
        "structure": "myproject-code_structure"
      }
    }
  ]
}

---

Create Project

POST /api/projects
Content-Type: application/json

{
  "name": "My Project",
  "path": "/Users/username/Projects/myproject",
  "description": "My awesome project"
}

Response:

{
  "success": true,
  "project_id": 1,
  "name": "My Project",
  "mcps_created": ["memories", "index", "profile", "docs", "structure"]
}

---

Get Project

GET /api/projects/{id}

Response:

{
  "id": 1,
  "name": "My Project",
  "path": "/Users/username/Projects/myproject",
  "description": "My awesome project",
  "created_at": "2025-10-31 12:00:00",
  "mcps": {
    "memories": "myproject-project_memories",
    "index": "myproject-project_index",
    "profile": "myproject-project_profile",
    "docs": "myproject-knowledge_docs",
    "structure": "myproject-code_structure"
  }
}

---

Get Project MCPs

GET /api/projects/{id}/mcps

Response:

{
  "project_id": 1,
  "mcps": {
    "memories": {
      "name": "myproject-project_memories",
      "document_count": 42,
      "status": "active"
    },
    "index": {
      "name": "myproject-project_index",
      "document_count": 3100,
      "status": "active"
    },
    "structure": {
      "name": "myproject-code_structure",
      "document_count": 1,
      "status": "active"
    }
  }
}

---

Set KB Folders

POST /api/projects/{id}/folders
Content-Type: application/json

{
  "memories": "/docs/memories",
  "docs": "/docs"
}

---

Get KB Folders

GET /api/projects/{id}/folders

---

Ingest Document into Project

POST /api/projects/{id}/ingest-document
Content-Type: multipart/form-data

mcp_type=docs
file=@/path/to/document.md

MCP Types: memories, index, profile, docs, structure

---

Delete Project

DELETE /api/projects/{id}

Response:

{
  "success": true,
  "message": "Project and all associated knowledge bases deleted"
}

---

Hooks System

Enable Hook

POST /api/projects/{id}/hooks/{mcp_type}/enable
Content-Type: application/json

{
  "folder_path": "/docs"
}

MCP Types: memories, index, profile, docs

Response:

{
  "success": true,
  "message": "Hook enabled for {mcp_type}",
  "folder_path": "/docs"
}

---

Disable Hook

POST /api/projects/{id}/hooks/{mcp_type}/disable

Response:

{
  "success": true,
  "message": "Hook disabled for {mcp_type}"
}

---

Manual Sync

POST /api/projects/{id}/hooks/sync
Content-Type: application/json

{
  "mcp_type": "docs"
}

Response:

{
  "success": true,
  "files_synced": 15,
  "files_added": 3,
  "files_updated": 12
}

---

Get Hook Status

GET /api/projects/{id}/hooks

Response:

{
  "project_id": 1,
  "hooks": {
    "memories": {
      "enabled": true,
      "folder_path": "/docs/memories",
      "last_sync": "2025-10-31 12:00:00"
    },
    "docs": {
      "enabled": true,
      "folder_path": "/docs",
      "last_sync": "2025-10-31 11:45:00"
    }
  }
}

---

File Watcher

Start Watcher

POST /api/watcher/start/{project_id}

Response:

{
  "success": true,
  "project_id": 1,
  "watching_folders": ["/docs", "/docs/memories"],
  "status": "active"
}

---

Stop Watcher

POST /api/watcher/stop/{project_id}

Response:

{
  "success": true,
  "project_id": 1,
  "status": "stopped"
}

---

Restart Watcher

POST /api/watcher/restart/{project_id}

---

Get Watcher Status

GET /api/watcher/status

Response:

{
  "active_watchers": [
    {
      "project_id": 1,
      "project_name": "My Project",
      "folders": ["/docs", "/docs/memories"],
      "files_watched": 42,
      "status": "active"
    }
  ],
  "total_watchers": 1
}

---

Authentication

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "your-password"
}

Response:

{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "user": {
    "id": 1,
    "email": "user@example.com",
    "name": "John Doe"
  }
}

---

Get Current User

GET /api/auth/me
Authorization: Bearer <access_token>

Response:

{
  "id": 1,
  "email": "user@example.com",
  "name": "John Doe",
  "created_at": "2025-10-31 12:00:00"
}

---

Check Auth Status

GET /api/auth/status

Response:

{
  "auth_enabled": true,
  "require_login": true
}

---

Utilities

List Ollama Models

GET /api/ollama/models

Response:

{
  "models": [
    {
      "name": "llama3.2:latest",
      "size": "4.7GB",
      "modified_at": "2025-10-31 12:00:00"
    }
  ]
}

---

Browse Directory

GET /api/browse-directory?path=/Users/username/Projects

Response:

{
  "path": "/Users/username/Projects",
  "directories": [
    {
      "name": "myproject",
      "path": "/Users/username/Projects/myproject",
      "size": 1048576
    }
  ],
  "files": [
    {
      "name": "README.md",
      "path": "/Users/username/Projects/README.md",
      "size": 2048
    }
  ]
}

---

Health Check

System Health

GET /health

Response:

{
  "status": "healthy",
  "timestamp": "2025-10-31T12:00:00",
  "components": {
    "sqlite": {
      "status": "healthy",
      "connected": true,
      "database": "claude-os.db",
      "tables": 15,
      "knowledge_bases": 10
    },
    "ollama": {
      "status": "healthy",
      "connected": true,
      "models": 3,
      "host": "http://localhost:11434"
    },
    "redis": {
      "status": "healthy",
      "connected": true,
      "host": "localhost",
      "port": 6379
    }
  }
}

---

Error Responses

All endpoints return errors in this format:

{
  "detail": "Error message describing what went wrong"
}

Common HTTP Status Codes:

• 200 - Success
• 201 - Created
• 400 - Bad Request (invalid input)
• 401 - Unauthorized (authentication required)
• 404 - Not Found (resource doesn't exist)
• 500 - Internal Server Error

---

Rate Limiting

Currently no rate limiting is implemented. May be added in future versions.

---

Pagination

For endpoints that return large lists (projects, documents), pagination is not yet implemented. All results are returned in a single response.

---

WebSocket Support

WebSocket support for real-time updates is planned but not yet implemented.

---

Examples

Complete Hybrid Indexing Workflow

# 1. Create structure KB
curl -X POST http://localhost:8051/api/kb \
  -H "Content-Type: application/json" \
  -d '{
    "name": "myproject-code_structure",
    "kb_type": "generic",
    "description": "Structural index"
  }'

# 2. Run Phase 1 (structural - FAST!)
curl -X POST http://localhost:8051/api/kb/myproject-code_structure/index-structural \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/Users/username/Projects/myproject",
    "token_budget": 2048
  }'

# 3. Create index KB
curl -X POST http://localhost:8051/api/kb \
  -H "Content-Type: application/json" \
  -d '{
    "name": "myproject-project_index",
    "kb_type": "generic",
    "description": "Semantic index"
  }'

# 4. Run Phase 2 (semantic - selective)
curl -X POST http://localhost:8051/api/kb/myproject-project_index/index-semantic \
  -H "Content-Type: application/json" \
  -d '{
    "project_path": "/Users/username/Projects/myproject",
    "selective": true,
    "code_structure_kb": "myproject-code_structure"
  }'

# 5. Get repo map for Claude's context
curl "http://localhost:8051/api/kb/myproject-code_structure/repo-map?token_budget=1024"

---

Support

For issues, questions, or contributions:

• GitHub: https://github.com/brobertsaz/claude-os/issues
• Documentation: https://github.com/brobertsaz/claude-os/tree/main/docs

---

Last Updated: 2025-10-31 API Version: 1.0