Rerank

Rerank documents by medical relevance to a query.

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

Reranks a list of documents by their relevance to a given query. Optimized for medical content, this API significantly improves search result quality for healthcare applications.

Request Body

Parameter	Type	Required	Default	Description
`model`	string	Yes	—	Must be `persly-rerank-v1`
`query`	string	Yes	—	The search query to rank documents against. Must be non-empty.
`documents`	array	Yes	—	Documents to rerank. 1–1,000 items. Each item is a string or `{"text": "..."}` object.
`top_n`	integer \| null	No	`null`	Return only the top N results. If `null`, all documents are returned. Must be ≥ 1.
`return_documents`	boolean	No	`true`	Include the document text in the response

Response Body

Field	Type	Description
`id`	string	Unique request ID in `rrk_{hex}` format
`object`	string	Always `"rerank"`
`created`	integer	Unix timestamp
`model`	string	`"persly-rerank-v1"`
`results`	array	Ranked results, sorted by relevance (highest first)
`results[].index`	integer	Original index in the input `documents` array
`results[].relevance_score`	number	Relevance score (0.0–1.0)
`results[].document`	object \| null	Document text (when `return_documents: true`)
`results[].document.text`	string	The document text
`usage`	object	Usage information
`usage.search_count`	integer	Number of search units billed (⌈documents / 100⌉)
`usage.documents_count`	integer	Number of documents processed

Examples

Basic Reranking

curl https://api.persly.ai/v1/rerank \
  -H "Authorization: Bearer $PERSLY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "persly-rerank-v1",
    "query": "treatment options for rheumatoid arthritis",
    "documents": [
      "Methotrexate is the anchor drug in RA treatment, typically started at 7.5-15mg weekly.",
      "Osteoarthritis is a degenerative joint disease primarily affecting weight-bearing joints.",
      "Biologic DMARDs such as TNF inhibitors are used when conventional DMARDs fail.",
      "Physical therapy and exercise are important adjuncts in managing inflammatory arthritis."
    ],
    "top_n": 3
  }'

import requests

response = requests.post(
    "https://api.persly.ai/v1/rerank",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={
        "model": "persly-rerank-v1",
        "query": "treatment options for rheumatoid arthritis",
        "documents": [
            "Methotrexate is the anchor drug in RA treatment, typically started at 7.5-15mg weekly.",
            "Osteoarthritis is a degenerative joint disease primarily affecting weight-bearing joints.",
            "Biologic DMARDs such as TNF inhibitors are used when conventional DMARDs fail.",
            "Physical therapy and exercise are important adjuncts in managing inflammatory arthritis.",
        ],
        "top_n": 3,
    },
)

data = response.json()
for result in data["results"]:
    print(f"[{result['relevance_score']:.3f}] {result['document']['text'][:80]}...")

const response = await fetch("https://api.persly.ai/v1/rerank", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "persly-rerank-v1",
    query: "treatment options for rheumatoid arthritis",
    documents: [
      "Methotrexate is the anchor drug in RA treatment, typically started at 7.5-15mg weekly.",
      "Osteoarthritis is a degenerative joint disease primarily affecting weight-bearing joints.",
      "Biologic DMARDs such as TNF inhibitors are used when conventional DMARDs fail.",
      "Physical therapy and exercise are important adjuncts in managing inflammatory arthritis.",
    ],
    top_n: 3,
  }),
});

const data = await response.json();
for (const result of data.results) {
  console.log(`[${result.relevance_score.toFixed(3)}] ${result.document.text.slice(0, 80)}...`);
}

Response

{
  "id": "rrk_a1b2c3d4e5f6a1b2c3d4e5f6",
  "object": "rerank",
  "created": 1709000000,
  "model": "persly-rerank-v1",
  "results": [
    {
      "index": 0,
      "relevance_score": 0.95,
      "document": {"text": "Methotrexate is the anchor drug in RA treatment, typically started at 7.5-15mg weekly."}
    },
    {
      "index": 2,
      "relevance_score": 0.89,
      "document": {"text": "Biologic DMARDs such as TNF inhibitors are used when conventional DMARDs fail."}
    },
    {
      "index": 3,
      "relevance_score": 0.72,
      "document": {"text": "Physical therapy and exercise are important adjuncts in managing inflammatory arthritis."}
    }
  ],
  "usage": {
    "search_count": 1,
    "documents_count": 4
  }
}

Using Object Documents

Documents can be passed as objects with a text field:

{
  "model": "persly-rerank-v1",
  "query": "diabetes management",
  "documents": [
    {"text": "Insulin therapy is essential for type 1 diabetes management."},
    {"text": "Regular eye exams are recommended for diabetic patients."}
  ]
}

Pricing

Billing is based on search units: 1 search unit = up to 100 documents.

Documents	Search Units	Cost
1–100	1	$0.002
101–200	2	$0.004
901–1,000	10	$0.020

Errors

Status	Code	Cause
400	`model_not_found`	Invalid model (must be `persly-rerank-v1`)
400	`invalid_request`	Empty query, empty documents, or invalid document format
400	`documents_limit_exceeded`	More than 1,000 documents
401	`authentication_error`	Invalid API key
429	`quota_exceeded`	Free credits exhausted
429	`spending_limit_exceeded`	Monthly spending limit reached

Rerank

On this page