# Search the web

Passages from the web that match a question, each with the page it came from.

`POST /search`

Search the web index for a question. The answer is a list of passages, each with a score and the page it came from, ready for an agent to quote. Needs the scope `search:read`.

| Field | Type | Meaning |
| --- | --- | --- |
| `query` | string | Required. The question, 1 to 1,000 characters. |
| `topK` | number | Optional. How many passages to return, 1 to 50. |

Request:

```
curl -sS https://api.rivier.ai/search \
  -H "Authorization: Bearer $RIVIER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "query": "opening hours of the national library" }'
```

Response:

```
{
  "highlights": [
    {
      "text": "…",
      "score": 0.82,
      "source": { "url": "https://example.org/visit" }
    }
  ]
}
```

The same operation is the command `rivier search web search` and the MCP tool `rivier_search`.