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.
| Field | Type | Required | Meaning |
|---|---|---|---|
query | String | Yes | Non-empty search query. |
documents | Array of strings | Yes | Non-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 asBAD_REQUESTwith a message. - 401: missing or invalid project credential.
- 403: missing
rerank.create. - 429: request-rate limit reached.
- 502: reranking failed, returned as
UPSTREAM_FAILURE.