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

# search

> Structured, citable retrieval from the clinical knowledge base.

`search` queries the clinical knowledge base and returns **structured document
units** — never a free-form blob. It is the retrieval foundation the other
capabilities build on.

**Endpoint:** `POST /v1/search` · **MCP tool:** `search`

## When to use it

* You want the **raw sources** for a query, to display or cite yourself.
* You are building your own synthesis and just need retrieval.

For a written answer instead of sources, use [answer](/en/capabilities/answer).

## Request

| Field                 | Type   | Notes                                   |
| --------------------- | ------ | --------------------------------------- |
| `query`               | string | Free-text clinical query (French).      |
| `source_ids`          | int\[] | Optional. Restrict to specific sources. |
| `limit`               | int    | Max document units (default 10).        |
| `max_chunks_per_unit` | int    | Best chunks kept per unit (default 3).  |

## Response

Each unit is one source document with its best-matching chunks:

```json theme={null}
{
  "query": "antibioprophylaxie chirurgie colorectale",
  "units": [
    {
      "document_id": 14853,
      "document_title": "Antibioprophylaxie en chirurgie",
      "reco_id": 900,
      "reco_title": "Chirurgie colorectale",
      "source_id": 3,
      "source_name": "SFAR",
      "year": "2023",
      "deep_link": "https://.../14853.pdf",
      "score": 0.91,
      "chunks": [
        { "chunk_index": 0, "content": "Céfazoline en dose unique...", "score": 0.91 }
      ]
    }
  ],
  "retrieved_pool": 100
}
```

<Note>
  `limit` caps the number of **document units**, not chunks. `retrieved_pool` is
  the diagnostic count of raw chunks swept before grouping — it is not bounded by
  `limit`.
</Note>

Run it live in the **API Reference** tab.