API Endpoints

Search Endpoints

Search Project

curl -X POST http://localhost:3333/api/v1/search/project \
  -H "Content-Type: application/json" \
  -d '{
    "query": "authentication logic",
    "projectId": "my-project",
    "maxResults": 10,
    "minScore": 0.3
  }'

Endpoint: POST /api/v1/search/project Description: Contextual search using hybrid vector + keyword search with RRF ranking.

Request Body

query

string

required

Search query (natural language or keywords)

projectId

string

required

Project ID to search in

projectPath

string

Project path for auto-reindex if needed

maxResults

number

default:10

Maximum number of results to return

minScore

number

Minimum relevance score (0-1)

responseMode

string

default:"summary"

Response format: summary or full

autoReindex

boolean

default:true

Automatically reindex if project is stale

include

array

Glob patterns to include (e.g., ["*.ts", "*.tsx"])

exclude

array

Glob patterns to exclude (e.g., ["node_modules/**"])

explainScores

boolean

default:false

Include score explanations in response

Response

success

boolean

Indicates if the search was successful

data

object

Search results data

Show properties

results

array

Array of search results with file paths, content, and relevance scores

totalResults

number

Total number of results found

query

string

The original search query

Search Code

Endpoint: POST /api/v1/search/code Description: Semantic code search (alias for search/project).

curl -X POST http://localhost:3333/api/v1/search/code \
  -H "Content-Type: application/json" \
  -d '{
    "query": "JWT token validation",
    "projectId": "my-project",
    "limit": 10
  }'

Request Body

query

string

required

Code search query

projectId

string

required

Project ID to search in

limit

number

default:10

Maximum results to return

Memory Endpoints

Store Memory

Endpoint: POST /api/v1/memory/store Description: Store a new memory in the hierarchical memory system (local SQLite).

curl -X POST http://localhost:3333/api/v1/memory/store \
  -H "Content-Type: application/json" \
  -d '{
    "content": "User prefers TypeScript for new features",
    "type": "preference",
    "importance": 0.8,
    "tags": ["typescript", "preferences"]
  }'

Request Body

content

string

required

Content to store in memory

type

string

required

Type of memory: preference, conversation, code, decision, or pattern

userId

string

User identifier for scoping memory

projectId

string

Project identifier for scoping memory

sessionId

string

Session identifier for scoping memory

agentId

string

Agent identifier for scoping memory

Response

success

boolean

Indicates if the memory was stored successfully

data

object

Stored memory details

Show properties

string

Unique identifier for the stored memory

content

string

The stored content

createdAt

string

ISO 8601 timestamp of when the memory was created

Search Memories

Endpoint: POST /api/v1/memory/search Description: Search stored memories using semantic search across sessions.

curl -X POST http://localhost:3333/api/v1/memory/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "typescript preferences",
    "limit": 10,
    "minImportance": 0.5
  }'

Request Body

query

string

required

Search query (what to remember)

userId

string

Filter by user ID

projectId

string

Filter by project ID

sessionId

string

Filter by session ID

agentId

string

Filter by agent ID

types

array

Filter by memory types (e.g., ["preference", "decision"])

limit

number

default:10

Maximum results to return

minImportance

number

Minimum importance score (0-1)

includePersistent

boolean

default:true

Include persistent memories

format

string

default:"toon"

Output format: json or toon

List Memories

Endpoint: POST /api/v1/memory/list Description: List stored memories with optional filters (no semantic search, ordered by creation date).

curl -X POST http://localhost:3333/api/v1/memory/list \
  -H "Content-Type: application/json" \
  -d '{
    "type": "preference",
    "limit": 50,
    "offset": 0
  }'

Request Body

type

string

Filter by memory type: preference, conversation, code, decision, or pattern

limit

number

default:50

Maximum number of memories to return

offset

number

default:0

Offset for pagination

minImportance

number

default:0

Minimum importance score (0-1)

Response

success

boolean

Indicates if the list operation was successful

data

object

List results

Show properties

memories

array

Array of memory objects

total

number

Total count of memories matching filters

limit

number

Applied limit

offset

number

Applied offset

Project Endpoints

Index Project

Endpoint: POST /api/v1/project/index Description: Start indexing a project directory in background. Returns a jobId immediately.

curl -X POST http://localhost:3333/api/v1/project/index \
  -H "Content-Type: application/json" \
  -d '{
    "projectPath": "/home/user/my-project",
    "projectId": "my-project",
    "forceReindex": false,
    "warmCache": true
  }'

Request Body

projectPath

string

required

Absolute path to the project directory to index

projectId

string

Unique identifier for the project (defaults to directory name)

forceReindex

boolean

default:false

Force reindexing even if project is already indexed

warmCache

boolean

default:false

Pre-cache common queries after indexing completes

warmupQueries

array

Custom queries to pre-cache (e.g., ["authentication", "API routes"])

Response

success

boolean

Indicates if the indexing job was started

data

object

Job information

Show properties

jobId

string

Unique identifier for tracking the indexing job

status

string

Initial job status (usually pending or running)

Get Index Status

Endpoint: GET /api/v1/project/index/status/:jobId Description: Get the status and progress of an async indexing job.

curl http://localhost:3333/api/v1/project/index/status/job-123

URL Parameters

jobId

string

required

Job ID returned by POST /project/index

Response

success

boolean

Indicates if the status check was successful

data

object

Job status details

Show properties

jobId

string

The job identifier

status

string

Job status: pending, running, completed, or failed

progress

number

Indexing progress (0-100)

error

string

Error message if status is failed

List Projects

Endpoint: GET /api/v1/project/list Description: List all indexed projects with document counts and metadata.

curl http://localhost:3333/api/v1/project/list

Response

success

boolean

Indicates if the list operation was successful

data

object

Projects list

Show properties

projects

array

Array of indexed projects with metadata

total

number

Total number of indexed projects

Context Endpoints

Compress Context

Endpoint: POST /api/v1/context/compress Description: Compress context using semantic compression (keeps structure, removes details).

curl -X POST http://localhost:3333/api/v1/context/compress \
  -H "Content-Type: application/json" \
  -d '{
    "content": "...code or text content...",
    "strategy": "code_structure",
    "targetRatio": 0.7,
    "language": "typescript"
  }'

Request Body

content

string

required

Content to compress

strategy

string

default:"code_structure"

Compression strategy:

code_structure - Extract function signatures, types, exports
conversation_summary - Summarize conversation history
semantic_dedup - Remove semantically duplicate content
hierarchical - Multi-level compression

targetRatio

number

Target compression ratio (0-1). Lower = more aggressive compression

language

string

Programming language for code compression (e.g., typescript, python, javascript)

Response

success

boolean

Indicates if compression was successful

data

object

Compression results

Show properties

compressed

string

The compressed content

originalSize

number

Original content size in characters

compressedSize

number

Compressed content size in characters

compressionRatio

number

Achieved compression ratio (0-1)

tokenSavings

number

Estimated tokens saved

Get Optimized Context

Endpoint: POST /api/v1/context/optimized Description: Retrieve and compress context with maximum token efficiency (search + compress in one call).

curl -X POST http://localhost:3333/api/v1/context/optimized \
  -H "Content-Type: application/json" \
  -d '{
    "query": "authentication implementation",
    "projectId": "my-project",
    "maxTokens": 4000,
    "maxResults": 5
  }'

Request Body

query

string

required

Search query to find relevant context

projectId

string

required

Project ID for code context

projectPath

string

Project path for auto-reindex if needed

maxTokens

number

default:4000

Maximum tokens in returned context

maxResults

number

default:5

Maximum search results to include before compression

Response

success

boolean

Indicates if context optimization was successful

data

object

Optimized context

Show properties

context

string

The optimized, compressed context ready for AI consumption

tokenCount

number

Estimated token count of returned context

sources

array

Source files included in the context

Analytics Endpoints

Get Analytics

Endpoint: POST /api/v1/analytics Description: Get search analytics and performance metrics.

curl -X POST http://localhost:3333/api/v1/analytics \
  -H "Content-Type: application/json" \
  -d '{"type": "summary"}'

Request Body

type

string

required

Type of analytics:

summary - Overall usage summary
project - Project-specific statistics
query - Query performance analysis
cache - Cache hit rates and performance
recent - Recent search activity

projectId

string

Required when type is project

query

string

Required when type is query

limit

number

default:10

Maximum results for recent type

Response

success

boolean

Indicates if analytics retrieval was successful

data

object

Analytics data (structure varies by type)

System Endpoints

Health Check

Endpoint: GET /health Description: Simple health check endpoint.

curl http://localhost:3333/health

Response

{
  "status": "ok",
  "service": "th0th-tools-api",
  "version": "1.0.0",
  "timestamp": "2026-03-09T12:00:00.000Z"
}

System Information

Endpoint: GET /api/v1/system/info Description: Get detailed system and environment information.

curl http://localhost:3333/api/v1/system/info

Response

version

string

API version

service

string

Service name

node

string

Node.js version

platform

string

Operating system platform

arch

string

CPU architecture

uptime

number

Process uptime in seconds

memory

object

Memory usage statistics

dataDir

string

Data directory path

databases

object

Database sizes and total storage

System Status

Endpoint: GET /api/v1/system/status Description: Check health status of all services.

curl http://localhost:3333/api/v1/system/status

Response

{
  "status": "healthy",
  "services": {
    "memories": true,
    "vectorStore": true,
    "searchCache": true,
    "analytics": true,
    "keywordSearch": true,
    "embeddingCache": true
  },
  "timestamp": "2026-03-09T12:00:00.000Z"
}

System Metrics

Endpoint: GET /api/v1/system/metrics Description: Get aggregated metrics and performance data.

curl http://localhost:3333/api/v1/system/metrics

Local-First Health Check

Endpoint: GET /api/v1/system/health/local Description: Comprehensive health check of all local services (Ollama, SQLite databases, data directory).

curl http://localhost:3333/api/v1/system/health/local

Response

status

string

Overall health status: healthy, degraded, or unhealthy

services

object

Individual service health checks

Show properties

ollama

object

Ollama service status and latency

databases

object

SQLite database availability

dataDirectory

boolean

Data directory accessibility

recommendations

array

Actionable recommendations for any detected issues

Ollama Status

Endpoint: GET /api/v1/system/ollama Description: Check Ollama availability, list installed models, and verify embedding model configuration.

curl http://localhost:3333/api/v1/system/ollama

Response

status

string

Ollama service status: healthy or unavailable

models

array

List of installed embedding models

configuredModel

string

Currently configured embedding model

baseUrl

string

Ollama base URL

latency

number

Response latency in milliseconds

Error Responses

All endpoints return errors in a consistent format:

{
  "success": false,
  "error": "Descriptive error message"
}

Common Errors

Project Not Indexed

Error: Project 'xyz' not found. Please index it first.Solution: Index the project using POST /api/v1/project/index before searching.

Ollama Not Available

Error: Ollama service is not availableSolution: Ensure Ollama is running (ollama serve) and the embedding model is installed.

Invalid Parameters

Error: Validation error: [field] is requiredSolution: Check that all required parameters are provided in the request body.

Database Error

Error: Database operation failedSolution: Check that the data directory exists and has proper permissions.

Rate Limiting & Quotas

No rate limiting or quotas are enforced in the default local-first deployment. Configure limits via middleware for production use.

WebSocket Support

WebSocket support for real-time indexing progress is planned for a future release. Use polling with GET /project/index/status/:jobId for now.

Next Steps

REST API Overview

Learn about authentication and response formats

MCP Tools

Use th0th via Model Context Protocol

Integration Guides

Integrate with OpenCode, VSCode, or Docker

Configuration

Configure embedding providers and advanced settings

REST API

MCP Tools

CLI

Documentation Index

​Search Endpoints

​Search Project

​Request Body

​Response

​Search Code

​Request Body

​Memory Endpoints

​Store Memory

​Request Body

​Response

​Search Memories

​Request Body

​List Memories

​Request Body

​Response

​Project Endpoints

​Index Project

​Request Body

​Response

​Get Index Status

​URL Parameters

​Response

​List Projects

​Response

​Context Endpoints

​Compress Context

​Request Body

​Response

​Get Optimized Context

​Request Body

​Response

​Analytics Endpoints

​Get Analytics

​Request Body

​Response

​System Endpoints

​Health Check

​Response

​System Information

​Response

​System Status

​Response

​System Metrics

​Local-First Health Check

​Response

​Ollama Status

​Response

​Error Responses

​Common Errors

​Rate Limiting & Quotas

​WebSocket Support

​Next Steps

REST API Overview

MCP Tools

Integration Guides

Configuration

Search Endpoints

Search Project

Request Body

Response

Search Code

Request Body

Memory Endpoints

Store Memory

Request Body

Response

Search Memories

Request Body

List Memories

Request Body

Response

Project Endpoints

Index Project

Request Body

Response

Get Index Status

URL Parameters

Response

List Projects

Response

Context Endpoints

Compress Context

Request Body

Response

Get Optimized Context

Request Body

Response

Analytics Endpoints

Get Analytics

Request Body

Response

System Endpoints

Health Check

Response

System Information

Response

System Status

Response

System Metrics

Local-First Health Check

Response

Ollama Status

Response

Error Responses

Common Errors

Rate Limiting & Quotas

WebSocket Support

Next Steps