---
title: "Search & Orama"
description: "Examples for the compiled edge search index and the public search API."
canonical_url: "https://docs.bulkheados.com/ai/search/"
template: "page-node"
schema_type: "WebPage"
---

<div class="docs-content">
<p class="docs-lead">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.</p>

<h2 id="endpoint-shape">Endpoint Shape</h2>
<p>The public endpoint accepts a search query and optional filters for result count, node type, domain, and visibility.</p>

<pre><code class="language-http">GET /api/v1/search?q=bulkhead&amp;limit=5&amp;type=inform&amp;visibility=external
Accept: application/json</code></pre>

<h2 id="response-example">Response Example</h2>
<pre><code class="language-json">{
  "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"
    }
  }
}</code></pre>

<h2 id="filters">Useful Filters</h2>
<table>
<thead><tr><th>Query param</th><th>Purpose</th><th>Example</th></tr></thead>
<tbody>
<tr><td><code>q</code></td><td>The required search term</td><td><code>?q=federation</code></td></tr>
<tr><td><code>limit</code></td><td>Maximum results, capped by the API</td><td><code>?limit=10</code></td></tr>
<tr><td><code>type</code></td><td>Filter by node type</td><td><code>?type=inform</code></td></tr>
<tr><td><code>domain</code></td><td>Filter by domain slug</td><td><code>?domain=default</code></td></tr>
<tr><td><code>visibility</code></td><td>Restrict to internal or external content</td><td><code>?visibility=external</code></td></tr>
</tbody>
</table>

<h2 id="build-cycle">Build Cycle</h2>
<p>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.</p>

<div class="docs-callout docs-callout--info">
<p><strong>Why Orama here?</strong> It keeps search runtime cheap. The expensive work happens during compile, then the public search endpoint reads from the serialized index.</p>
</div>
</div>