API reference

Rerank

Score documents by how well they answer a query, most relevant first. POST /v1/rerank takes the Cohere and Jina request shape, so retrieval pipelines can rerank their search results before they reach a chat model.

Rerank documents#

POST/v1/rerank

Request body

modelstringrequired: A rerank model ID from the list below, or GET /v1/models?kind=rerank.
querystringrequired: What you're searching for. Must not be empty.
documentsarrayrequired: 1 to 1,000 documents to score, each a string or an object with a text string ({"text": "…"}), so search results can be passed as they come.
top_ninteger: Return only this many results, the best first. Every document is still scored (and billed); left out, all are returned.
return_documentsboolean: true adds each result's document.text, so you needn't look it up by index. Off by default.

The response carries x-request-id and the rate-limit headers. Rate limits, spend caps, project budgets and model locks apply as they do to chat.

curl https://fullsendai.com/v1/rerank \  -H "Authorization: Bearer $FULLSEND_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "model": "qwen3-reranker-0.6b",    "query": "How do I reset my password?",    "documents": [      "Our office is open 9 to 5.",      "To reset your password, open Settings and choose Reset password.",      "Passwords must be 12 characters."    ],    "top_n": 2,    "return_documents": true  }'

Response

{  "id": "req_e5f1e364e5e8179612135381",  "model": "qwen3-reranker-0.6b",  "results": [    {      "index": 1,      "relevance_score": 0.9989,      "document": { "text": "To reset your password, open Settings and choose Reset password." }    },    {      "index": 2,      "relevance_score": 0.0021,      "document": { "text": "Passwords must be 12 characters." }    }  ],  "usage": { "prompt_tokens": 265, "total_tokens": 265 }}

The response#

idstring: The request's ID, the same as its x-request-id header.
modelstring: The FullsendAI model ID you called.
results[]array: Sorted by relevance_score, highest first. index is the document's position in your documents array; relevance_score is the model's score (higher is more relevant; compare scores within one call rather than across models); document appears with return_documents.
usage.prompt_tokensinteger: Input tokens, as billed: the query read with each document. total_tokens is the same number.

Limits#

1,000 documents a call. Larger sets need several calls; scores from one model are comparable between them.
Query and document fit the context window. Each document is read together with the query, so keep documents to passage size (a few hundred tokens) for the best results and price.
Kinds don't mix. A reranker called at a chat or embeddings endpoint, or another kind of model here, answers 400 invalid_model_kind. See Errors.

Rerank models#

No rerank model is live just now. Ask GET /v1/models?kind=rerank for the current list.

curl

curl "https://fullsendai.com/v1/models?kind=rerank" -H "Authorization: Bearer $FULLSEND_API_KEY"

Pricing#

You pay for input tokens only, at the model's input price per million: the query and every document, whatever top_n is. There are no output tokens. Each call shows on its row in Logs with its cost; plan allowance is spent first, then your prepaid balance. See Pricing and billing.

Stuck? Email [email protected]System status Changelog