Skip to main content

Create rerankings

POST /projects/:projectid/rerank

Scores candidate documents against a query. Use it after an initial search to decide which passages are most relevant.

This endpoint scores the text you send. It does not retrieve documents, search the Library, or sort the response for you.

Authentication and request​

Use a project key with rerank.create in Authorization, without Bearer. Replace :projectid with the key's project ID and send Content-Type: application/json.

FieldTypeRequiredMeaning
queryStringYesNon-empty search query.
documentsArray of stringsYesNon-empty list of candidate passages to score. Every item must contain non-whitespace text.

There is no public model selection, custom task instruction, or top_n parameter.

Using the Quickstart variables:

curl --include --request POST \
--header "Authorization: ${INTELLECTIBLE_PROJECT_API_KEY}" \
--header "Content-Type: application/json" \
--data '{"query":"When can I cancel?","documents":["Customers can cancel before their renewal date.","Orders are delivered within five working days."]}' \
"${INTELLECTIBLE_PUBLIC_API_URL}/projects/${INTELLECTIBLE_PROJECT_ID}/rerank"

Response​

200 OK returns one score per submitted document, in input order:

{
"data": [
{"score": 0.93},
{"score": 0.17}
]
}

These are illustrative scores. data[0].score belongs to documents[0], and so on. Pair scores with your original documents or IDs, then sort by descending score and take the number of results your application needs.

Higher scores indicate greater relevance to this query. Do not treat them as calibrated probabilities that an answer is correct, or assume a single threshold works equally well for every dataset.

Choose candidates carefully​

Send a focused candidate set from your initial search rather than the entire document collection. Keep passages relevant and reasonably sized; long document text may be truncated during scoring.

Preserve original indices while sorting so each result retains its document ID and source metadata. You can then pass the top passages to chat completions as context.

Errors​

  • 400: missing, empty, or malformed query/documents, returned as BAD_REQUEST with a message.
  • 401: missing or invalid project credential.
  • 403: missing rerank.create.
  • 429: request-rate limit reached.
  • 502: reranking failed, returned as UPSTREAM_FAILURE.

See Errors, limits and retries.