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/api/v1/search/assisted

Authorization

BearerAuth

AuthorizationBearer <token>

API key authentication. Pass your key in the Authorization header as Bearer sk_live_.... An X-API-Key: sk_live_... header is also accepted as an alternative. Keys are created in the Redpine Connect dashboard under Settings > API Keys.

Keys come in two kinds. A live key (sk_live_...) searches real content and spends credits. A sandbox key (sk_test_...) returns canned results at no cost and never reaches licensed content, so you can build and test an integration before spending anything. Sandbox responses have the same shape as live ones and every result is marked synthetic, so going live is a matter of swapping the key. Check the X-Billing-Mode response header to confirm which you are using.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

allowClarification?boolean

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.

Defaulttrue

collection?|

Collection to search. Provide either this or collections, not both.

Defaultnull

collections?array<string>|

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.

Items1 <= items <= 5

Defaultnull

filters?|

Same filter forms as /api/v1/search/query; applied to every internal search.

Defaultnull

imageMaxHeight?integer

Maximum image height in pixels

Range100 <= value <= 1080

Default600

imageMaxWidth?integer

Maximum image width in pixels

Range100 <= value <= 1920

Default800

imageQuality?integer

JPEG quality for fetched images

Range1 <= value <= 100

Default75

includeFigures?boolean

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.

Defaultfalse

includeMetadata?boolean

Whether to include metadata in results

Defaulttrue

limit?integer

Maximum verified results to return.

Range1 <= value <= 30

Default10

query*string

Search query text, or a whole document such as a patient case or chart note (max 16000 characters)

Length1 <= length <= 16000

Response Body

`application/json`

curl -X POST "https://example.com/api/v1/search/assisted" \  -H "Content-Type: application/json" \  -d '{    "query": "string"  }'

{  "billing": {    "chargedResults": 0,    "tokensCharged": 0  },  "clarification": {    "question": "string",    "reason": ""  },  "discovery": {    "callout": {      "kind": "add_payment_method",      "message": "string"    },    "intent": "sources",    "metricsNote": null,    "nextActions": [      {        "action": "string",        "hint": "string"      }    ],    "queryId": "string",    "scopes": [      {        "collection": "string",        "displayName": "string",        "issnValuesSeen": 0,        "items": [          {            "hIndex": null,            "impactFactor": null,            "issnL": null,            "issns": [              "string"            ],            "kind": "journal",            "publisher": null,            "title": "string"          }        ],        "note": null,        "offset": 0,        "publishers": [          "string"        ],        "rankedBy": null,        "sampledEntries": 0,        "shown": 0,        "titleOnly": 0,        "total": 0,        "truncatedInventory": false,        "unranked": [          {            "hIndex": null,            "impactFactor": null,            "issnL": null,            "issns": [              "string"            ],            "kind": "journal",            "publisher": null,            "title": "string"          }        ],        "unresolvedIssns": 0      }    ],    "text": "string",    "topic": null  },  "filterWarnings": null,  "iterationsRun": 0,  "journalMetricExpansions": null,  "latencyMs": 0,  "queryId": "string",  "queryUnderstanding": {    "aspects": [      "string"    ],    "caseSummary": "",    "entities": [      "string"    ],    "filters": {},    "intent": "",    "subQuestions": [      "string"    ]  },  "results": [    {      "collection": null,      "doiUrl": null,      "id": "string",      "metadata": null,      "relevance": {        "judgeScore": 0,        "matchedTerms": [          "string"        ],        "rationale": ""      },      "section": null,      "subQuestion": null,      "text": "string"    }  ],  "status": "results"}

Assisted search (verified results only)

Authorization

Request Body

Response Body

200application/json

401application/json

403application/json

422application/json

429application/json

503application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`