# Search and research

Web search, cited answers, research runs, watched topics and browser sessions.

Scopes for this area: `search:read`, `search:write` and `search:admin`.

33 operations.

## interest

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/research/interests` | Topics an agent keeps watching. | read | `rivier search interest list` |
| POST | `/research/interests` | Add a topic to watch. | write | `rivier search interest create` |
| GET | `/research/interests/{id}` | One topic. | read | `rivier search interest get` |
| PATCH | `/research/interests/{id}` | Change a topic. | write | `rivier search interest update` |
| DELETE | `/research/interests/{id}` | Stop watching a topic. | write | `rivier search interest delete` |
| POST | `/research/interests/{id}/pause` | Pause a topic. | write | `rivier search interest pause` |
| POST | `/research/interests/{id}/resume` | Resume a topic. | write | `rivier search interest resume` |
| POST | `/research/interests/{id}/run` | Research a topic now. | write | `rivier search interest run` |

## research

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/research/effective` | The research settings in force for an agent. | read | `rivier search research effective` |
| GET | `/research/budget` | What research may still spend. | read | `rivier search research budget` |
| POST | `/research/search` | A grounded web search for an agent, metered. | write | `rivier search research search` |
| POST | `/research` | Start a multi-step research run. | read | `rivier search research start` |
| GET | `/research/{id}` | A research run's state and result. | read | `rivier search research get` |
| GET | `/research/{id}/events` | A research run's progress as server-sent events. | read | `rivier search research events` |
| POST | `/research/{id}/cancel` | Stop a research run. | write | `rivier search research cancel` |

## run

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/research/runs` | Research runs. | read | `rivier search run list` |
| GET | `/research/runs/{id}` | One research run. | read | `rivier search run get` |

## note

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/research/notes` | Findings waiting for a decision. | read | `rivier search note list` |
| POST | `/research/notes/{id}/decide` | Accept or discard a finding. | write | `rivier search note decide` |

## conflict

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/research/conflicts` | Findings that disagree with memory. | read | `rivier search conflict list` |
| POST | `/research/conflicts/{id}/decide` | Resolve a conflict. | write | `rivier search conflict decide` |

## web

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| POST | `/search` | Search the index: highlights with citations. | read | `rivier search web search` |
| POST | `/answer` | A grounded, cited answer; streams as server-sent events on request. | read | `rivier search web answer` |

## browser

| Method | Route | What it does | Level | Command |
| --- | --- | --- | --- | --- |
| GET | `/browser/sessions` | Open browser sessions. | read | `rivier search browser list` |
| POST | `/browser/sessions` | Open a browser session. | write | `rivier search browser open` |
| GET | `/browser/sessions/{id}` | One browser session. | read | `rivier search browser get` |
| DELETE | `/browser/sessions/{id}` | Close a session. | write | `rivier search browser close` |
| POST | `/browser/sessions/{id}/navigate` | Go to an address. | write | `rivier search browser navigate` |
| POST | `/browser/sessions/{id}/act` | Do something on the page, in words. | write | `rivier search browser act` |
| POST | `/browser/sessions/{id}/fill` | Fill a form. | write | `rivier search browser fill` |
| POST | `/browser/sessions/{id}/observe` | What can be done on the page. | write | `rivier search browser observe` |
| POST | `/browser/sessions/{id}/extract` | Pull structured data from the page. | write | `rivier search browser extract` |
| POST | `/browser/sessions/{id}/read` | The page as text. | write | `rivier search browser read` |