Bobbin can run as an HTTP REST API server for centralized deployments, shared team use, or webhook-driven indexing.
bobbin serve --server # HTTP on port 3030 (default)
bobbin serve --server --port 8080 # Custom port
bobbin serve --server --mcp # HTTP + MCP stdio simultaneously
The server binds to 0.0.0.0 on the specified port and includes CORS headers for browser-based clients.
Method Path Description
GET/searchSemantic/hybrid/keyword search GET/grepKeyword/regex pattern search GET/contextTask-aware context assembly GET/chunk/{id}Read a specific chunk by ID GET/readRead file lines by path and range GET/relatedFind temporally coupled files GET/refsFind symbol definitions and usages GET/symbolsList symbols in a file GET/hotspotsIdentify high-churn complex files GET/impactPredict change impact GET/reviewDiff-aware review context GET/similarFind similar code or duplicate clusters GET/primeProject overview with live stats GET/beadsSearch indexed beads/issues GET/statusIndex statistics GET/metricsPrometheus metrics POST/webhook/pushTrigger re-indexing (for CI/CD)
Parameter Type Default Description
qstring required Search query modestring hybridSearch mode: hybrid, semantic, keyword typestring all Filter by chunk type limitinteger 10 Maximum results repostring all Filter by repository
curl "http://localhost:3030/search?q=error+handling&limit=5"
Parameter Type Default Description
patternstring required Search pattern ignore_casebool false Case-insensitive search regexbool false Enable regex matching typestring all Filter by chunk type limitinteger 10 Maximum results repostring all Filter by repository
curl "http://localhost:3030/grep?pattern=handleAuth&limit=5"
Parameter Type Default Description
qstring required Task description budgetinteger 500 Max lines of content depthinteger 1 Coupling expansion depth max_coupledinteger 3 Max coupled files per seed limitinteger 20 Max initial search results coupling_thresholdfloat 0.1 Min coupling score repostring all Filter by repository
curl "http://localhost:3030/context?q=refactor+auth+flow&budget=300"
Parameter Type Default Description
filestring required File path (relative to repo root) start_lineinteger required Start line number end_lineinteger required End line number contextinteger 0 Extra context lines before/after
curl "http://localhost:3030/read?file=src/main.rs&start_line=1&end_line=20"
Parameter Type Default Description
filestring required File path to find related files for limitinteger 10 Maximum results thresholdfloat 0.0 Min coupling score
curl "http://localhost:3030/related?file=src/auth.rs&limit=5"
Parameter Type Default Description
symbolstring required Symbol name to find typestring all Filter by symbol type limitinteger 20 Max usage results repostring all Filter by repository
curl "http://localhost:3030/refs?symbol=parse_config"
Parameter Type Default Description
filestring required File path repostring all Filter by repository
curl "http://localhost:3030/symbols?file=src/config.rs"
Parameter Type Default Description
sincestring 1 year agoTime window for churn analysis limitinteger 20 Maximum results thresholdfloat 0.0 Min hotspot score
curl "http://localhost:3030/hotspots?since=6+months+ago&limit=10"
Parameter Type Default Description
targetstring required File or file:function target depthinteger 1 Transitive depth (1-3) modestring combinedSignal: combined, coupling, semantic, deps limitinteger 15 Maximum results thresholdfloat 0.1 Min impact score repostring all Filter by repository
curl "http://localhost:3030/impact?target=src/auth.rs&depth=2"
Parameter Type Default Description
diffstring unstagedDiff spec: unstaged, staged, branch:<name>, or commit range budgetinteger 500 Max lines of content depthinteger 1 Coupling expansion depth repostring all Filter by repository
curl "http://localhost:3030/review?diff=staged&budget=300"
Parameter Type Default Description
targetstring - Chunk ref or text (required unless scan=true) scanbool false Scan for duplicate clusters thresholdfloat 0.85/0.90 Min similarity threshold limitinteger 10 Max results or clusters repostring all Filter by repository cross_repobool false Cross-repo comparison in scan mode
curl "http://localhost:3030/similar?target=src/auth.rs:login&limit=5"
curl "http://localhost:3030/similar?scan=true&threshold=0.9"
Parameter Type Default Description
sectionstring - Specific section to show briefbool false Compact overview only
curl "http://localhost:3030/prime?brief=true"
Parameter Type Default Description
qstring required Search query priorityinteger - Filter by priority (1-4) statusstring - Filter by status assigneestring - Filter by assignee rigstring - Filter by rig name limitinteger 10 Maximum results enrichbool true Enrich with live Dolt data
curl "http://localhost:3030/beads?q=auth+bug&status=open"
Returns index statistics in JSON format.
curl http://localhost:3030/status
Returns Prometheus-compatible metrics.
curl http://localhost:3030/metrics
Triggers re-indexing. Useful for CI/CD pipelines or git webhook integrations.
curl -X POST http://localhost:3030/webhook/push
When a remote bobbin server is running, CLI commands can delegate to it instead of accessing local storage:
bobbin search "auth" --server http://localhost:3030
bobbin status --server http://localhost:3030
The --server flag is a global option available on all commands. When set, the CLI acts as a thin client that forwards requests to the HTTP server.
Run bobbin on a shared machine with a large codebase indexed once:
# On the server
bobbin init
bobbin index
bobbin serve --server --port 3030
Team members connect via --server flag or configure their AI client to point at the server.
Add a webhook step to your CI pipeline to keep the index fresh:
# After deploy or merge
curl -X POST http://bobbin-server:3030/webhook/push
Run both HTTP and MCP simultaneously for maximum flexibility:
bobbin serve --server --mcp
This starts the HTTP server on the configured port and the MCP stdio server concurrently. The MCP server handles AI client connections while the HTTP server handles REST API requests and webhooks.