Assisted search

How this differs from Search

/search/query runs one hybrid retrieval pass and returns whatever ranks highest. /search/assisted runs a multi-round agent loop: it reads the query for entities, intent, and aspects, plans internal searches to cover them, verifies each candidate chunk actually addresses the query, and either replans or stops once it has enough verified evidence (or concludes there isn't any).

Billing differs too: only delivered, verified results are charged. A clarification request or an honest "no relevant results" answer costs nothing -- internal search fan-out and LLM tokens spent along the way are absorbed by Redpine, not billed to you. See the Rate Limits reference for the shared billing and rate-limit headers.

POST /api/v1/search/assisted

Runs the agentic search loop and returns verified results, a clarifying question, or an explicit no-relevant-results outcome. Accepts the same filters as /search/query, applied to every internal search.

Request body

Parameter	Type	Required	Description
`collection`	string	One of `collection`/`collections`	Collection name to search
`collections`	string[]	One of `collection`/`collections`	Collections to search together (max 5)
`query`	string	Yes	Natural-language question (max 1000 characters)
`limit`	integer	No	Maximum verified results to return (default 10, max 30)
`filters`	object \| null	No	Same filter forms as `/search/query`, applied to every internal search
`allow_clarification`	boolean	No	Whether the endpoint may respond with a clarifying question instead of results (default true)
`include_metadata`	boolean	No	Include chunk metadata in results (default true)
`include_figures`	boolean	No	Fetch and attach figure images as base64 in metadata.figures[].image_data, for delivered results only (default false, requires include_metadata)

Response fields

Field	Type	Description
`status`	`"results"` \| `"clarification_needed"` \| `"no_relevant_results"`	Outcome of the assisted search
`queryUnderstanding`	object	How the query was read: entities, intent, aspects, and any structured filters named in the query text
`results`	array	Verified results. Empty unless status is `results`
`clarification`	object \| null	The clarifying question and reason. Set only when status is `clarification_needed`
`billing`	object	What was actually charged: `chargedResults` and `tokensCharged`
`queryId`	string	Query identifier for audit reference
`latencyMs`	integer	End-to-end latency in milliseconds
`iterationsRun`	integer	Number of search + replan rounds executed
`filterWarnings`	array \| null	Advisory warnings for filter fields with no payload index; omitted when there are none
`journalMetricExpansions`	array \| null	How each journal-metric filter condition resolved to ISSNs; omitted when no metric filter was used

Result object

Field	Type	Description
`id`	string	Chunk/point ID
`text`	string	Chunk text content
`metadata`	object \| null	Chunk metadata (if `include_metadata=true`)
`collection`	string \| null	Origin collection of this result. Populated only for requests made with the `collections` (multi-collection) form
`doiUrl`	string \| null	Resolvable DOI link (`https://doi.org/{doi}`)
`section`	string \| null	Comma-joined source section(s) of the article (abstract, introduction, background, methods, results, discussion, conclusion, case, supplementary, other)
`relevance`	object	Relevance verdict: `matchedTerms`, `judgeScore` (0..1), and a one-sentence `rationale`

Example request (cURL)

curl -X POST "https://api.redpine.ai/api/v1/search/assisted" \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "collection": "my-collection",
    "query": "Does topical retinoid use increase photosensitivity?",
    "limit": 10,
    "allow_clarification": true,
    "include_metadata": true
  }'

Example request (Python)

import requests

response = requests.post(
    "https://api.redpine.ai/api/v1/search/assisted",
    headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
    json={
        "collection": "my-collection",
        "query": "Does topical retinoid use increase photosensitivity?",
        "limit": 10,
        "allow_clarification": True,
        "include_metadata": True,
    },
)

data = response.json()
if data["status"] == "results":
    for result in data["results"]:
        print(result["relevance"]["judgeScore"], result["text"][:200])
elif data["status"] == "clarification_needed":
    print(data["clarification"]["question"])
else:
    print("No relevant results")

Example request (TypeScript)

const response = await fetch(
  "https://api.redpine.ai/api/v1/search/assisted",
  {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_live_YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      collection: "my-collection",
      query: "Does topical retinoid use increase photosensitivity?",
      limit: 10,
      allow_clarification: true,
      include_metadata: true,
    }),
  }
);

const data = await response.json();
if (data.status === "results") {
  for (const result of data.results) {
    console.log(result.relevance.judgeScore, result.text.slice(0, 200));
  }
} else if (data.status === "clarification_needed") {
  console.log(data.clarification.question);
}

Example response (verified results)

{
  "status": "results",
  "queryUnderstanding": {
    "entities": ["retinoid", "photosensitivity"],
    "intent": "Determine whether an adverse effect is associated with a treatment",
    "aspects": ["mechanism of action", "clinical outcomes"],
    "filters": {}
  },
  "results": [
    {
      "id": "abc123",
      "text": "Topical retinoids increase skin sensitivity to UV light by thinning the stratum corneum...",
      "metadata": {
        "title": "Retinoid Dermatology Review"
      },
      "collection": null,
      "doiUrl": "https://doi.org/10.1234/example",
      "section": "discussion",
      "relevance": {
        "matchedTerms": ["retinoid", "photosensitivity"],
        "judgeScore": 0.91,
        "rationale": "Directly states the photosensitizing mechanism of topical retinoids."
      }
    }
  ],
  "clarification": null,
  "billing": {
    "chargedResults": 1,
    "tokensCharged": 612
  },
  "queryId": "qry_a1b2c3d4e5f6",
  "latencyMs": 3840,
  "iterationsRun": 2
}

Clarification flow

When allowClarification is true (the default) and the query is too underspecified to search confidently, the endpoint returns status: "clarification_needed" with a question instead of running the full search. Re-issue the request with the query augmented by the user's answer. Clarification requests are never billed.

{
  "status": "clarification_needed",
  "queryUnderstanding": {
    "entities": ["treatment"],
    "intent": "Unclear -- no specific condition or drug named",
    "aspects": [],
    "filters": {}
  },
  "results": [],
  "clarification": {
    "question": "Which treatment and condition are you asking about?",
    "reason": "The query does not name a specific drug, procedure, or condition to search for."
  },
  "billing": {
    "chargedResults": 0,
    "tokensCharged": 0
  },
  "queryId": "qry_f6e5d4c3b2a1",
  "latencyMs": 1120,
  "iterationsRun": 1
}

Set allow_clarification to false if your client can't present a follow-up turn -- the endpoint will then do its best with the query as given rather than asking back, and either return results or no_relevant_results.

Filtering

The filters parameter accepts the same simple and structured-DSL forms as /search/query, and is applied to every internal search the agent runs. See the full Filtering reference for operators, indexed fields, and journal-metric filters.

Assisted search

On this page