# Search

URL: /code/platform/search · Id: `capability:search`

> Search answers keyword, semantic and hybrid queries across a namespace, indexes every write, and returns only what the caller may read.

Search finds [Things](/business/nouns/thing) in a [Startup](/business/nouns/startup)'s namespace by words, by meaning, or both. Every write is indexed, and every result respects the caller's [Permissions](/business/nouns/permission).

## Contract
- Three modes: `fulltext`, `semantic` and `hybrid`, the default. Hybrid ranks by keyword and by meaning, then reranks the merged list.
- A record is searchable when its write returns. The index is a projection of the database and rebuilds from it.
- Results are ranked candidates, never a complete list. To get every match, filter a [Collection](/business/nouns/collection) with `where` instead.
- Each result carries its `$id`, its score and the [Version](/business/nouns/version) it read.
- Results continue from the returned cursor, never from computed offsets.
- A caller sees only the records its Permissions read. A Startup's [Sites](/business/nouns/site) search only the Collections a [Setting](/business/nouns/setting) makes public.
- An [Agent](/business/nouns/agent) searches first: the MCP `search` tool, then `fetch`, then `do`.
- A ranking change can run as an [Experiment](/business/nouns/experiment), judged on click-through and task success.

## Verbs
| Verb | Object | Event |
| --- | --- | --- |
| [Thing.list](/business/nouns/thing/list) | [Thing](/business/nouns/thing) | None. |

## Interfaces
- [API](/code/api/reference)
- [SDK](/code/sdk/reference)
- [CLI](/code/cli/reference)
- [MCP](/code/mcp/reference)

## Example
```ts
// shutterswap.com resells used camera gear and declares a `Listing` Noun. A buyer types "weather sealed body".
import { $ } from 'startup-builder'

const hits = await $.search('weather sealed body', { limit: 20 })
// [{ $id: 'https://api.sb/shutterswap.com/listings/listing_41', score: 0.91, version: 'v12' }, …]
```