<!-- source: https://docs.redpine.ai/docs/api-reference/search/searchAssisted -->
# Assisted search (verified results only)

> Agentic search: the query is interpreted, one or more internal searches are planned and run, every candidate is verified as actually addressing the query, and only verified results are returned.

**Billing differs from `/search/query`:** only delivered, verified results are charged. A clarification request or an honest no-results answer costs nothing. Internal search fan-out and LLM tokens are absorbed by Redpine.

Accepts the same `filters` as `/search/query`, applied to every internal search.

`POST` `https://api.redpine.ai/api/v1/search/assisted`

## Authentication

```
Authorization: Bearer sk_live_YOUR_API_KEY
```

## Request body

| Field | Type | Required | Description |
|---|---|---|---|
| `allowClarification` | boolean | no | If true, the endpoint may return a clarifying question instead of results when the query is too underspecified. Set false if your client cannot do a follow-up turn. |
| `collection` | string | no | Collection to search. Provide either this or `collections`, not both. |
| `collections` | array | no | Collections to search together (max 5). Results are merged into one relevance-ranked list and each result is labeled with its origin collection. Provide either this or 'collection', not both. |
| `filters` | object | no | Same filter forms as `/api/v1/search/query`; applied to every internal search. |
| `imageMaxHeight` | integer | no | Maximum image height in pixels |
| `imageMaxWidth` | integer | no | Maximum image width in pixels |
| `imageQuality` | integer | no | JPEG quality for fetched images |
| `includeFigures` | boolean | no | Fetch and attach figure images (base64, in metadata.figures[].image_data) for the delivered results only. Adds latency; requires `includeMetadata`. `includeImages` is accepted as a deprecated alias. |
| `includeMetadata` | boolean | no | Whether to include metadata in results |
| `limit` | integer | no | Maximum verified results to return. |
| `query` | string | yes | Search query text, or a whole document such as a patient case or chart note (max 16000 characters) |

## Responses

| Status | Description |
|---|---|
| `200` | Verified results, a clarification request, or an explicit no-relevant-results outcome |
| `401` | Missing or invalid API key |
| `403` | API key does not have access to the requested collection |
| `422` | Validation error (e.g. query too long, invalid filter) |
| `429` | Rate or quota limit exceeded |
| `503` | Assisted search temporarily unavailable |

### 200 response fields

| Field | Type | Required | Description |
|---|---|---|---|
| `billing` | object | yes | What was actually charged — only delivered, verified results are billed. |
| `clarification` | object | no | Set only when status is `clarification_needed`. |
| `discovery` | object | no | A catalogue answer: what data sources, publishers or journals your key can reach. Present only when the query asked about the catalogue rather than for literature; then `results` is empty and nothing was charged (`X-Query-Cost: 0.000000`). |
| `filterWarnings` | array | no | Advisory warnings about the supplied filter — for example filtering on a known field with no payload index, which is matched by scanning, or a collection excluded because it holds only open-access content and the filter asked for open_access=false. The search still runs. Omitted when there are none. |
| `iterationsRun` | integer | yes | Number of search+replan rounds executed |
| `journalMetricExpansions` | array | no | How each journal-metric condition resolved to ISSNs; omitted when no metric filter was used |
| `latencyMs` | integer | yes | End-to-end latency in milliseconds |
| `queryId` | string | yes | Query ID for audit reference |
| `queryUnderstanding` | object | yes | How the endpoint read the query. |
| `results` | object[] | no | Verified results (empty unless status='results') |
| `status` | `results` \| `clarification_needed` \| `no_relevant_results` | yes | Outcome of the assisted search |