> ## Documentation Index
> Fetch the complete documentation index at: https://docs.breadbowl.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search

> Search an index and use the ranked results

Send a natural-language query to an index:

The example uses the environment variables configured in the [quickstart](/quickstart).

```bash theme={null}
curl --fail-with-body \
  "$BREADBOWL_API_URL/v1/indexes/$BREADBOWL_INDEX_ID/search" \
  -H "Authorization: Bearer $BREADBOWL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How do I request a refund?",
    "filter": {"status": "published"}
  }'
```

## Use the results

Results are ordered by relevance. Every response also includes request-level usage:

```json theme={null}
{
  "results": [{
    "doc_id": "help-center:refunds",
    "chunk_id": "chk_000000",
    "chunk_index": 0,
    "score": 0.82,
    "metadata": {"status": "published"}
  }],
  "usage": {
    "input_tokens": 8,
    "document_count": 0,
    "chunk_count": 1,
    "candidate_count": 24,
    "latency_ms": 96
  }
}
```

BreadBowl Embed does not return the original text. For each result:

1. Load the source record using `doc_id`.
2. Apply your application's current access rules.
3. Preserve the returned order when showing results or building context.

Do not use `chunk_id` as a permanent business ID; it can change when a document is replaced.

## Adjust search

| Field         | Default | What it controls                           |
| ------------- | ------: | ------------------------------------------ |
| `top_k`       |    `10` | Maximum results returned                   |
| `candidate_k` |   `100` | Candidates considered before final ranking |
| `filter`      |    none | Exact matches on top-level metadata        |

Start with the defaults. Increase `candidate_k` only after testing with representative queries. Scores are for ordering one response; do not assume a fixed score range.

Filters are not an authorization boundary. Always check access after loading the source record.

An empty `results` array is valid. Confirm that documents were added to the same index, then retry without a filter.