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. Returns ranked search results with relevance scores.

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.005) for quick search or `"advanced"` ($0.01) 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_sources`	boolean	No	`true`	Include search result documents in the response

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 (when `include_answer: true`)
`results`	array \| null	Search results (when `include_sources: true`)
`results[].title`	string	Document title
`results[].url`	string	Document URL
`results[].content`	string	Relevant excerpt from the document
`results[].score`	number	Relevance score
`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["results"]:
    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.94
    },
    {
      "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.88
    },
    {
      "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.82
    }
  ],
  "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
}

Errors

Status	Code	Cause
400	`missing_required_field`	Empty or missing `query`
400	`invalid_request`	Invalid `search_depth` value
401	`authentication_error`	Invalid API key
429	`quota_exceeded`	Free credits exhausted
429	`spending_limit_exceeded`	Monthly spending limit reached