Bulkhead OS uses a compiled Orama index for tenant search. Queries hit KV-backed search data at runtime, so readers get search results without direct database reads on every request.

Endpoint Shape

The public endpoint accepts a search query and optional filters for result count, node type, domain, and visibility.

GET /api/v1/search?q=bulkhead&limit=5&type=inform&visibility=external
Accept: application/json

Response Example

{
  "results": [
    {
      "title": "Search & Orama",
      "url": "/ai/search",
      "excerpt": "Bulkhead OS uses a compiled Orama index for tenant search...",
      "score": 0.91,
      "node_type": "inform",
      "domain": "Bulkhead Documentation"
    },
    {
      "title": "Introduction",
      "url": "/introduction",
      "excerpt": "BulkheadOS is a company operating graph for complex software companies...",
      "score": 0.78,
      "node_type": "inform",
      "domain": "Bulkhead Documentation"
    }
  ],
  "meta": {
    "query": "bulkhead",
    "count": 2,
    "limit": 5,
    "indexStats": {
      "documentCount": 24,
      "indexSizeBytes": 18244,
      "builtAt": "2026-04-07T10:00:00.000Z"
    }
  }
}

Useful Filters

Query param	Purpose	Example
q	The required search term	?q=federation
limit	Maximum results, capped by the API	?limit=10
type	Filter by node type	?type=inform
domain	Filter by domain slug	?domain=default
visibility	Restrict to internal or external content	?visibility=external

Build Cycle

The search index is rebuilt during compilation. If the endpoint returns an empty result set with a message that the index is not built yet, run a compile to regenerate the KV-backed index for the tenant.