# Answer a question

One answer to a question, with a numbered source for every claim it makes.

`POST /answer`

Ask a question and get one answer written from what the search found. Every claim carries a numbered marker that points to its source. 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 write the answer from, 1 to 20. |
| `forceEscalate` | boolean | Optional. Use the larger model for this answer from the start. |
| `stream` | boolean | Optional. Send the answer as server-sent events while it is written. |

Request:

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

Response:

```
{
  "answer": "The library opens at 09:00 on weekdays [1] and at 10:00 on Saturdays [2].",
  "citations": [
    { "marker": 1, "url": "https://example.org/visit", "text": "…" },
    { "marker": 2, "url": "https://example.org/hours", "text": "…" }
  ],
  "claims": [
    {
      "text": "The library opens at 09:00 on weekdays.",
      "verdict": "supported",
      "quotes": ["…"],
      "grounded": true
    }
  ],
  "confidence": 0.84,
  "sufficiency": "supported",
  "conflicts": []
}
```

`claims` lists each statement with the quotes that support it. `confidence` is between 0 and 1. `sufficiency` says whether the sources were enough, and when they were not the answer says so and does not guess. `conflicts` lists sources that disagree.

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