Documentation
Reference

API Reference

Sirchmunk exposes a REST API when running in server mode (sirchmunk serve or sirchmunk web serve).

API Endpoints

MethodEndpointDescription
POST/api/v1/searchExecute a search query (JSON response when complete)
POST/api/v1/search/streamSame request body; SSE stream of logs plus final result or error
GET/api/v1/search/statusCheck server and LLM configuration (includes max_concurrent_searches)

Interactive Docs: When the server is running, visit http://localhost:8584/docs for Swagger UI.

Search API

POST /api/v1/search

Execute an intelligent search query. The handler returns JSON after the search finishes.

Request body: paths is optional (see Request parameters).

{
  "query": "How does authentication work?",
  "mode": "FAST",
  "paths": ["/path/to/project"],
  "max_depth": 10,
  "top_k_files": 20,
  "enable_dir_scan": true,
  "max_loops": 8,
  "max_token_budget": 131072,
  "include_patterns": ["*.py", "*.java"],
  "exclude_patterns": ["*test*", "*__pycache__*"],
  "return_context": false
}

Response:

{
  "success": true,
  "data": {
    "summary": "Markdown-formatted search result...",
    "context": null
  }
}

Request parameters

ParameterTypeDescription
querystringRequired. Natural-language search question.
pathsstring | string[]Optional. Root path(s) to search. If omitted, the server uses SIRCHMUNK_SEARCH_PATHS (if set), otherwise the process current working directory.
modestringSearch mode, e.g. FAST (default), DEEP, FILENAME_ONLY.
max_depthintMaximum directory depth.
top_k_filesintCap on files considered.
enable_dir_scanboolWhether to scan directories for candidates; default true.
max_loopsintDEEP mode: maximum agent / reasoning loops.
max_token_budgetintDEEP mode: token budget for the run; default 128K (131072).
include_patternsstring[]Glob patterns to include.
exclude_patternsstring[]Glob patterns to exclude.
return_contextboolWhen true, include extra context in the response (replaces legacy return_cluster).

POST /api/v1/search/stream

Same JSON body as POST /api/v1/search. The connection stays open and emits Server-Sent Events: progress logs during execution, then a final event with the completed result or an error payload.

GET /api/v1/search/status

Check server health, LLM configuration, and concurrency limits.

Response:

{
  "status": "ok",
  "llm_configured": true,
  "version": "0.0.6post1",
  "max_concurrent_searches": 4
}

Client Examples

cURL

# FAST mode (default, greedy search with 2 LLM calls); paths optional
curl -X POST http://localhost:8584/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How does authentication work?",
    "mode": "FAST",
    "paths": ["/path/to/project"]
  }'

# DEEP mode (comprehensive analysis with Monte Carlo sampling)
curl -X POST http://localhost:8584/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How does authentication work?",
    "paths": ["/path/to/project"],
    "mode": "DEEP"
  }'

# Filename search (no LLM required)
curl -X POST http://localhost:8584/api/v1/search \
  -H "Content-Type: application/json" \
  -d '{
    "query": "config",
    "paths": ["/path/to/project"],
    "mode": "FILENAME_ONLY"
  }'

Python (requests)

import requests

response = requests.post(
    "http://localhost:8584/api/v1/search",
    json={
        "query": "How does authentication work?",
        "paths": ["/path/to/project"],
    },
    timeout=300
)

data = response.json()
if data.get("success"):
    print(data.get("data", {}).get("summary", data))

Python (httpx, async)

import httpx
import asyncio

async def search():
    async with httpx.AsyncClient(timeout=300) as client:
        resp = await client.post(
            "http://localhost:8584/api/v1/search",
            json={
                "query": "find all API endpoints",
                "paths": ["/path/to/project"],
            }
        )
        data = resp.json()
        print(data.get("data", {}).get("summary", data))

asyncio.run(search())

JavaScript

const response = await fetch("http://localhost:8584/api/v1/search", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    query: "How does authentication work?",
    paths: ["/path/to/project"],
  })
});

const data = await response.json();
if (data.success) {
  console.log(data.data?.summary ?? data);
}

SSE streaming (POST /api/v1/search/stream)

cURL

curl -N -X POST http://localhost:8584/api/v1/search/stream \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -d '{"query":"How does authentication work?","mode":"FAST"}'

Python (httpx)

import httpx

url = "http://localhost:8584/api/v1/search/stream"
payload = {"query": "How does authentication work?", "mode": "FAST"}

with httpx.Client(timeout=None) as client:
    with client.stream(
        "POST",
        url,
        json=payload,
        headers={"Accept": "text/event-stream"},
    ) as response:
        response.raise_for_status()
        for line in response.iter_lines():
            if line:
                print(line)
docs