Search is the one endpoint most integrations start with, so it earns a page inside the guides as well as its row in the API tab. The generated contract below comes from this site's own OpenAPI spec; the console shows a working request against this very site.

Two behaviors worth knowing beyond the contract:

* The `degraded` flag reports runtime health, not configuration. A site with a working embedding key still answers `degraded: true` when the provider is down or rate limited, so a client can label keyword-only results instead of silently serving worse ones.
* Agents wanting full passages should use the MCP server's `search_docs` tool, which requests complete chunk text; the snippet field here is a display preview, never model grounding.

`POST /_readsmith/api/search`

Hybrid search over the site's indexed content: Postgres full-text fused with vector similarity when an embedding key is configured. No LLM is involved. `degraded: true` marks a response whose vector arm failed at request time, so the hits are keyword-only.

### Request body

`application/json` · required

- `query` string · required · min length: 1 · max length: 2000 — The search query or question.
- `version` string · optional — Docs version to scope to. Defaults to current.
- `locale` string · optional — Locale to scope to. Defaults to en.

### Responses

**200** — Ranked hits, possibly degraded to keyword-only.

`application/json`:

- `hits` array of SearchHit · required
  - `id` string · required — The chunk id.
  - `kind` string · required · options: `"doc"`, `"endpoint"` — Prose chunk or API operation.
  - `title` string · required — The page or operation title.
  - `snippet` string · required — A short preview for display. Never model grounding.
  - `text` string · optional — The full chunk text, present only when the caller asked for it.
  - `url` string · required — Deep link to the passage.
  - `anchor` string | null · required — The heading anchor within the page.
  - `headerPath` array of string · required — The heading trail above the passage.
  - `method` string | null · required — HTTP method, for endpoint hits.
  - `path` string | null · required — Operation path, for endpoint hits.
  - `score` number · required — Fused relevance score.
- `degraded` boolean · required — True when the vector arm was expected but failed at request time: these hits are keyword-only.

**400**

**429**

**503**