Claude OS API Reference

Base URL: http://localhost:8051

Complete reference for all Claude OS MCP Server API endpoints.

Knowledge Base Operations
Hybrid Indexing
Project Management
Agent-OS Spec Tracking
Real-Time Spec Watcher
Hooks System
File Watcher
Authentication
Utilities
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"
}

Agent-OS Spec Tracking (NEW)

Real-time tracking and visualization of agent-os specifications and tasks through the Kanban board.

Get Project Kanban Board

GET /api/projects/{id}/kanban?include_archived=false

Returns complete Kanban view with all specs and tasks grouped by status.

Response:

{
  "project_id": 1,
  "specs": [
    {
      "id": 1,
      "name": "Manual Appointment Times",
      "slug": "manual-appointment-times",
      "folder_name": "2025-10-29-manual-appointment-times",
      "path": "/path/to/project/agent-os/specs/2025-10-29-manual-appointment-times",
      "total_tasks": 71,
      "completed_tasks": 43,
      "status": "in_progress",
      "progress": 60.6,
      "archived": false,
      "tasks": {
        "todo": [...],
        "in_progress": [...],
        "done": [...],
        "blocked": [...]
      },
      "task_count_by_status": {
        "todo": 28,
        "in_progress": 0,
        "done": 43,
        "blocked": 0
      }
    }
  ],
  "summary": {
    "total_specs": 3,
    "total_tasks": 123,
    "completed_tasks": 56
  }
}

Sync Project Specs

POST /api/projects/{id}/specs/sync

Manually trigger sync of all spec files from agent-os/specs/ folder to database.

Response:

{
  "project_id": 1,
  "message": "Specs synced successfully",
  "synced": 0,
  "updated": 3,
  "total": 3,
  "errors": []
}

Get Spec Tasks

GET /api/specs/{spec_id}/tasks

Returns all tasks for a specific spec.

Response:

{
  "spec_id": 1,
  "tasks": [
    {
      "id": 53,
      "task_code": "PHASE1-TASK1",
      "phase": "Phase 1",
      "title": "Complete database layer",
      "description": "Implement all database models and migrations",
      "status": "done",
      "estimated_minutes": 60,
      "actual_minutes": 120,
      "risk_level": "medium",
      "dependencies": [],
      "started_at": "2025-10-29T10:00:00Z",
      "completed_at": "2025-10-29T12:00:00Z"
    }
  ]
}

Update Task Status

PATCH /api/tasks/{task_id}/status
Content-Type: application/json

{
  "status": "in_progress",
  "actual_minutes": 90
}

Valid Statuses:

todo - Not started
in_progress - Currently working
done - Completed
blocked - Waiting on dependencies

Response:

{
  "success": true,
  "old_status": "todo",
  "new_status": "in_progress"
}

Archive Spec

POST /api/specs/{spec_id}/archive

Archives a completed spec to declutter the Kanban board.

Unarchive Spec

POST /api/specs/{spec_id}/unarchive

Restores an archived spec.

Real-Time Spec Watcher (NEW)

Automatic file system monitoring for agent-os/specs/ folders. Detects changes to spec files and auto-syncs to database for real-time Kanban updates.

See: docs/guides/REALTIME_KANBAN_GUIDE.md for complete documentation.

Get Watcher Status

GET /api/spec-watcher/status

Response:

{
  "status": {
    "enabled": true,
    "projects_watched": 1,
    "projects": {
      "1": {
        "project_path": "/Users/you/Projects/myapp",
        "specs_path": "/Users/you/Projects/myapp/agent-os/specs",
        "watching": true
      }
    }
  }
}

Start Spec Watcher

POST /api/spec-watcher/start/{project_id}

Starts real-time file watching for a specific project's specs folder.

Response:

{
  "project_id": 1,
  "message": "Spec watcher started",
  "status": {
    "enabled": true,
    "projects_watched": 1
  }
}

Stop Spec Watcher

POST /api/spec-watcher/stop/{project_id}

Stops file watching for a specific project.

Start All Spec Watchers

POST /api/spec-watcher/start-all

Starts spec watchers for all projects in the database.

Auto-Start: Spec watchers automatically start when MCP server boots.

How it works:

Monitors agent-os/specs/**/*.md files
Detects changes with 2-second debounce
Auto-parses tasks in checkbox format
Updates database within 3 seconds
Kanban board auto-refreshes every 3 seconds

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

FilesExpand file tree

API_REFERENCE.md

Latest commit

History

API_REFERENCE.md

File metadata and controls

Claude OS API Reference

Table of Contents

Knowledge Base Operations

Create Knowledge Base

List Knowledge Bases

Get Knowledge Base Stats

List Documents in Knowledge Base

Query Knowledge Base

Upload Document

Import Directory

Delete Document

Delete Knowledge Base

Hybrid Indexing (NEW!)

Phase 1: Structural Indexing (Tree-Sitter)

Phase 2: Selective Semantic Indexing (Embeddings)

Get Repo Map

Project Management

List Projects

Create Project

Get Project

Get Project MCPs

Set KB Folders

Get KB Folders

Ingest Document into Project

Delete Project

Agent-OS Spec Tracking (NEW)

Get Project Kanban Board

Sync Project Specs

Get Spec Tasks

Update Task Status

Archive Spec

Unarchive Spec

Real-Time Spec Watcher (NEW)

Get Watcher Status

Start Spec Watcher

Stop Spec Watcher

Start All Spec Watchers

Hooks System

Enable Hook

Disable Hook

Manual Sync

Get Hook Status

File Watcher

Start Watcher

Stop Watcher

Restart Watcher

Get Watcher Status

Authentication

Login

Get Current User

Check Auth Status

Utilities

List Ollama Models

Browse Directory

Health Check

System Health

Error Responses

Rate Limiting

Pagination

WebSocket Support

Examples

Complete Hybrid Indexing Workflow

Support