Search

GET|POST /retrieve/search returns addressable, ranked hits from a BrainAPI brain. Use it to power documentation search, support portals, research discovery, incident consoles, catalogs, and any interface that needs ordered results with scores and snippets.

A search hit is deliberately smaller and more explicit than an answer. It tells the caller what matched, why it ranked, and where to retrieve or display it. Your application decides whether to show the hit, open the source, send it to an LLM, or begin a deeper investigation.

The mental model

Think of Search as a pipeline with three responsibilities:

1. Find candidates. BM25 finds exact terminology, dense retrieval finds semantic similarity, graph channels find connected nodes, and retriever plugins can add another candidate list.
2. Order candidates. BrainAPI fuses the first-stage lists and can optionally rerank a bounded head.
3. Shape the result. Metadata filters, catalog node mapping, query-gated personalization, truncation, and facets produce the final response.

The default path intentionally does less: it retrieves passages with BM25 and dense search and fuses the lists. Add graph channels, plugins, or personalization only when they address a measured problem.

Why Search is separate from Context

The same brain supports several read products, but they answer different caller needs:

/retrieve/context is not a hidden search endpoint. Enabling Search may change the passage mode available to Context, but it does not give Context ranked hits, facets, or Search plugins.

Before the first query

Search requires PostgreSQL because BrainAPI stores generated full-text data and indexes beside the passages and vector data. At least one of BM25 or dense retrieval must be enabled.

DATA_DB="postgresql"
SEARCH_ENABLED="true"
SEARCH_USE_DENSE="true"
SEARCH_USE_BM25="true"
SEARCH_FUSION="rrf"

Restart BrainAPI after changing configuration. Then ingest text into the same brain you will search. For a documentation corpus that does not need automatic graph enrichment, use skip_enrichment=true:

curl -X POST "<DEPLOYMENT_URL>/ingest/" \
  -H "Content-Type: application/json" \
  -H "BrainPAT: YOUR_BRAIN_PAT" \
  -H "X-Brain-ID: developer-docs" \
  -d '{
    "data": {
      "data_type": "text",
      "text_data": "AUTH-041 occurs when a refresh token has expired. Reauthenticate the client and request a new token."
    },
    "meta_keys": {
      "product": "identity",
      "locale": "en",
      "version": "2"
    },
    "skip_enrichment": true
  }'

Ingestion is asynchronous. Wait for the returned task to complete before treating an empty result as a ranking problem. See Saving text and ingestion tasks.

Why passages are the default

Passages are the most general searchable object: they exist for ordinary text ingestion, retain the source language, and work without a hand-built graph. Graph nodes are valuable only when their labels and relationships represent something useful to the query. Starting with passages gives every brain a predictable baseline and prevents an incomplete graph from silently replacing text recall.

First search

The same corpus can answer an exact diagnostic lookup and a semantic question:

curl -X POST "<DEPLOYMENT_URL>/retrieve/search" \
  -H "Content-Type: application/json" \
  -H "BrainPAT: YOUR_BRAIN_PAT" \
  -H "X-Brain-ID: developer-docs" \
  -d '{
    "query": "sign in fails after refresh token expires",
    "k": 10,
    "channels": ["passages"],
    "fusion": "rrf",
    "profile_stages": true
  }'

The exact AUTH-041 query gives BM25 a strong identifier signal. The natural-language query gives dense retrieval a chance to match the meaning even when the wording differs. With the default RRF fusion, a passage supported by both lists receives evidence from both without comparing incompatible raw score scales.

Why POST is the complete interface

GET is convenient for browser-addressable searches and simple integrations. It supports query, k, channels, node_labels, community_labels, expand, fusion, rerank, target, profile_stages, and header-based brain scoping.

POST uses the structured SearchRequestBody and additionally exposes extras for scalar metadata filters, fusion_alpha for convex-combination tuning, and mode for the deeper catalog candidate pool. Use POST for production clients whose search configuration may grow.

Anatomy of a response

{
  "hits": [
    {
      "id": "chunk-auth-041",
      "channel": "passages",
      "score": 0.0325,
      "scores": {
        "bm25": 7.84,
        "dense": 0.81,
        "rrf": 0.0325,
        "cc": null,
        "rerank": null,
        "plugin": null,
        "graph": null,
        "personalize": null
      },
      "snippet": "AUTH-041 occurs when a refresh token has expired...",
      "labels": [],
      "extras": {"product": "identity", "locale": "en", "version": "2"},
      "node_id": null
    }
  ],
  "stage_timings": {"search.retrieve": {"duration_ms": 42.1}},
  "channel_lists": {
    "dense": ["chunk-auth-041"],
    "bm25": ["chunk-auth-041"],
    "entities": [],
    "events": [],
    "communities": [],
    "neighbors": [],
    "literal": []
  },
  "facets": {
    "product": {"identity": 1},
    "locale": {"en": 1},
    "version": {"2": 1}
  },
  "node_ids": []
}

Read the response in layers:

• hits is the final ordered list your application normally consumes.
• score is the final ranking score; compare it only within the same request and configuration.
• scores exposes available component evidence. null means that stage did not score the hit.
• channel_lists is diagnostic and can contain candidates that did not survive later stages.
• extras contains scalar metadata. facets counts those values only over the returned hits.
• node_id links a passage to an addressable entity when a DOCID <id> marker is present. node_ids is the de-duplicated response-level list.
• stage_timings appears only when profile_stages=true; embed.query is separated from retrieval time.

Request reference

Query and result size

Candidate generation

Fusion and reranking

Filtering, personalization, and diagnostics

Channels and why to choose them

Graph channels can be combined with passages:

{
  "query": "authentication outages after the August gateway rollout",
  "k": 20,
  "channels": ["passages", "entities", "events"],
  "node_labels": ["SERVICE", "ENTITY"],
  "expand": "neighbors",
  "profile_stages": true
}

This remains a one-shot ranking request. Use agentic retrieval when answering the question requires following and verifying several relationships.

Common patterns

Exact identifiers

Keep channels=["passages"] and BM25 enabled for error codes, function names, ticket IDs, statutes, and version strings. Dense-only retrieval can blur small but decisive identifier differences.

Semantic questions

Use the default hybrid passage path for questions such as “how do I recover a client after its credentials expire?” Hybrid retrieval preserves exact evidence while allowing a paraphrase to match.

Hard metadata constraints

{
  "query": "reset a locked account",
  "k": 20,
  "channels": ["passages"],
  "extras": {"locale": "it", "product": "identity"}
}

Both values must match, case-insensitively. Filtering occurs after candidate retrieval, so a narrow filter may return fewer than k; BrainAPI does not repeatedly retrieve until the page fills.

Learned stages

Use Search SPLADE or Search ColBERT as explicit first-stage channels. Use Search Rerank when candidate recall is already good but the top order needs finer query-candidate comparison.

Why plugins are opt-in

Learned retrieval and reranking introduce model downloads, device requirements, index lifecycle, memory usage, and variable latency. They can also make relevance worse on a corpus unlike their training data. BrainAPI never silently substitutes a missing plugin or attaches Search plugins to /retrieve/context.

Troubleshooting

Continue learning

• Search levels — decide how far to escalate
• Search recipes — follow complete multi-domain workflows
• Search theory — understand the equations and stage ordering
• Catalog search and personalization — map passages to nodes and add preferences