Finder

AI-powered medical information search with optional answer generation.

POST https://api.persly.ai/v1/finder

Searches across medical information sources and optionally generates an AI-synthesized answer. When results are returned, each result includes a score field; with reranking, scores indicate relative relevance (higher means more relevant), and without reranking they may be 0.0.

The Finder endpoint always uses the persly-finder-v1 model — no model parameter is needed in the request.

Request Body

Parameter	Type	Required	Default	Description
`query`	string	Yes	—	Search query. Must be non-empty.
`search_depth`	string	No	`"basic"`	`"basic"` ($0.035) for quick search or `"advanced"` ($0.07) for comprehensive results
`max_results`	integer	No	`5`	Maximum number of results to return. Range: 1–20.
`include_answer`	boolean	No	`false`	Generate an AI-synthesized answer from search results
`include_domains`	string[] \| null	No	`null`	Apply best-effort domain filtering during retrieval. Values are normalized; invalid/non-normalized values can be ignored. Use Domains to discover common values; request-time validation does not enforce strict catalog membership.
`exclude_domains`	string[] \| null	No	`null`	Apply best-effort exclusion filtering during retrieval. Values are normalized; invalid/non-normalized values can be ignored. Use Domains to discover common values; request-time validation does not enforce strict catalog membership.

include_domains and exclude_domains are mutually exclusive. Sending both as non-empty arrays returns 422 validation error.

Response Body

Field	Type	Description
`id`	string	Unique request ID in `fnd_{hex}` format
`object`	string	Always `"finder.result"`
`created`	integer	Unix timestamp
`model`	string	`"persly-finder-v1"`
`query`	string	The input query (echoed back)
`answer`	string \| null	AI-generated answer. `null` when `include_answer: false` or no answer is generated.
`results`	array \| null	Search results. `null` when no results are returned.
`results[].title`	string	Document title
`results[].url`	string	Document URL
`results[].content`	string	Relevant excerpt from the document
`results[].score`	number	Relative relevance score for comparing returned results (higher means more relevant). Do not assume a fixed `0.0–1.0` range; `0.0` may be returned when reranking is not applied or when a score is unavailable.
`usage`	object	Usage information
`usage.query_count`	integer	Always `1`
`response_time`	number	Response time in seconds (2 decimal places)

Examples

Basic Search

curl https://api.persly.ai/v1/finder \
  -H "Authorization: Bearer $PERSLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "latest guidelines for managing chronic kidney disease",
    "max_results": 3
  }'

import requests

response = requests.post(
    "https://api.persly.ai/v1/finder",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "query": "latest guidelines for managing chronic kidney disease",
        "max_results": 3,
    },
)

data = response.json()
for result in (data.get("results") or []):
    print(f"[{result['score']:.2f}] {result['title']}")
    print(f"  {result['url']}")
    print(f"  {result['content'][:100]}...")
    print()

const response = await fetch("https://api.persly.ai/v1/finder", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    query: "latest guidelines for managing chronic kidney disease",
    max_results: 3,
  }),
});

const data = await response.json();
for (const result of data.results ?? []) {
  console.log(`[${result.score.toFixed(2)}] ${result.title}`);
  console.log(`  ${result.url}`);
}

Response

{
  "id": "fnd_a1b2c3d4e5f6a1b2c3d4e5f6",
  "object": "finder.result",
  "created": 1709000000,
  "model": "persly-finder-v1",
  "query": "latest guidelines for managing chronic kidney disease",
  "answer": null,
  "results": [
    {
      "title": "KDIGO 2024 Clinical Practice Guideline for CKD",
      "url": "https://kdigo.org/guidelines/ckd-evaluation-and-management/",
      "content": "The KDIGO 2024 guideline provides updated recommendations for the evaluation and management of chronic kidney disease...",
      "score": 0.0
    },
    {
      "title": "CKD Management - UpToDate",
      "url": "https://www.uptodate.com/contents/chronic-kidney-disease-management",
      "content": "Management of CKD involves addressing cardiovascular risk, blood pressure control, and slowing disease progression...",
      "score": 0.0
    },
    {
      "title": "Chronic Kidney Disease - NIDDK",
      "url": "https://www.niddk.nih.gov/health-information/kidney-disease/chronic-kidney-disease-ckd",
      "content": "Chronic kidney disease includes conditions that damage your kidneys and decrease their ability to keep you healthy...",
      "score": 0.0
    }
  ],
  "usage": {
    "query_count": 1
  },
  "response_time": 1.23
}

Advanced Search with AI Answer

curl https://api.persly.ai/v1/finder \
  -H "Authorization: Bearer $PERSLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are the SGLT2 inhibitor benefits in heart failure?",
    "search_depth": "advanced",
    "max_results": 5,
    "include_answer": true
  }'

Response with AI answer

{
  "id": "fnd_...",
  "object": "finder.result",
  "created": 1709000000,
  "model": "persly-finder-v1",
  "query": "What are the SGLT2 inhibitor benefits in heart failure?",
  "answer": "SGLT2 inhibitors have demonstrated significant benefits in heart failure management. Clinical trials (DAPA-HF, EMPEROR-Reduced) have shown reduced hospitalization rates and cardiovascular mortality...",
  "results": [...],
  "usage": {"query_count": 1},
  "response_time": 2.45
}

With Domain Filter

Use Domains to fetch common values before sending filters. Domain tokens are normalized, and invalid/non-normalized values can be ignored rather than raising request validation errors. Filtering is best-effort; off-domain results may still appear.

curl https://api.persly.ai/v1/finder \
  -H "Authorization: Bearer $PERSLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "metformin contraindications",
    "search_depth": "basic",
    "include_domains": ["nih.gov"],
    "max_results": 5
  }'

Exclude specific domains

curl https://api.persly.ai/v1/finder \
  -H "Authorization: Bearer $PERSLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "metformin contraindications",
    "search_depth": "basic",
    "exclude_domains": ["wikipedia.org"]
  }'

Errors

Status	Code	Cause
400	`missing_required_field`	Empty `query` string
400	`invalid_request`	Invalid `search_depth` value
422	—	Request validation error (missing required fields, invalid/non-coercible values, or both domain filters provided as non-empty arrays)
401	`authentication_error`	Missing or invalid Authorization header, or invalid API key (including malformed, unknown, or revoked keys).
402	`insufficient_credits`	Credit balance too low

Finder

On this page