REST API Overview

HTTP API for semantic search, memory, and context compression

Introduction

The th0th REST API provides HTTP endpoints for all core functionality:

• Semantic Search - Hybrid vector + keyword search with RRF ranking
• Memory - Persistent storage across sessions
• Project Indexing - Background indexing with progress tracking
• Context Compression - 70-98% token reduction
• Analytics - Usage metrics and cache performance
• System Health - Local-first service monitoring

Base URL

http://localhost:3333

Configure the port via the TH0TH_API_PORT environment variable.

Authentication

The API currently operates without authentication for local-first deployments. For production deployments, configure authentication via environment variables.

Starting the API

Development

bun run dev:api

Interactive Documentation

Swagger UI is available at:

http://localhost:3333/swagger

Response Format

All endpoints return JSON responses with a consistent structure:

Success Response

{
  "success": true,
  "data": {
    // endpoint-specific data
  }
}

Error Response

{
  "success": false,
  "error": "Error message describing what went wrong"
}

API Groups

Search

Semantic and keyword search in indexed projects

Memory

Store and recall information across sessions

Project

Index codebases and manage projects

Context

Compress and optimize context for AI models

Analytics

Usage patterns and performance metrics

System

Health checks and system information

Quick Examples

Health Check

curl http://localhost:3333/health

Rate Limiting

No rate limiting is enforced by default for local-first deployments. Configure rate limiting via middleware for production use.

CORS

CORS is enabled by default to allow browser-based clients. Configure CORS settings via the ElysiaJS CORS plugin in apps/tools-api/src/index.ts.

Error Handling

The API uses standard HTTP status codes:

Status Code	Description
200	Success
400	Bad Request - Invalid parameters
404	Not Found - Resource doesn’t exist
500	Internal Server Error - Server-side error

Local-First Architecture

The API is designed for 100% offline operation:

• Embeddings: Ollama (local) or cloud providers
• Vector Store: SQLite with vector extensions
• Memory: SQLite persistent storage
• Cache: Multi-level L1/L2 with TTL

No external services required for core functionality.

Next Steps

Explore Endpoints

View detailed endpoint documentation

MCP Integration

Use th0th via Model Context Protocol

Configuration

Configure embedding providers

OpenCode Plugin

Integrate with OpenCode editor