Reranker applies a second relevance-ranking pass to retrieved candidates; teams commonly use it in retrieval-augmented generation (RAG) workflows.
https://api.tokensmarket.ai/v1POST /rerankThe endpoint remains fixed. Use the parameter documentation on this page to replace the model ID and request data.
${base_url}/rerankReranker requests use a Bearer API Key for authentication and send the query and candidate documents as JSON.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
Authorization | string | Yes | — | Append the current workspace API Key after Bearer. Options / constraints: Bearer <API_KEY>. |
Content-Type | string | Yes | application/json | Send the request body as JSON. |
Submit query text and a list of candidate documents. The service returns the results ranked by relevance.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
model | string | Yes | — | The Reranker model ID in Model Market; it is case-sensitive. Options / constraints: Makes an exact copy of the currently available model ID. |
query | string | Yes | — | Non-empty query text used to compare for relevance. |
documents | string[] | Yes | — | A non-empty list of candidate documents to be reordered. Options / constraints: 1–500 items, each must be a non-empty string. |
top_n | integer | No | — | Returns only the N most relevant results. Options / constraints: Range is 1 to number of documents. |
instruct | string | No | — | Optional sort directive when supported by the current model. |
extra_body | object | No | — | Extension fields for the Unified API. Options / constraints: provider. |
extra_body.provider | object | No | — | Provider selection, filtering, sorting, and metric ranges. Options / constraints: Filter application order: ignore → ranges → only → sort → order. |
extra_body.provider.only | string[] | No | — | Provider allowlist. Selects only from the specified set. Options / constraints: Provider names are case-sensitive. |
extra_body.provider.ignore | string[] | No | — | Provider denylist. Excludes providers from the candidate set. Options / constraints: Non-empty only and ignore must not overlap; if verification fails, HTTP 400 / invalid_request will be returned. |
extra_body.provider.order | string[] | No | — | Boosts the priority of the specified provider last. Options / constraints: Provider names are case-sensitive. |
extra_body.provider.sort | string | string[] | No | — | Provider sort policy. Accepts multiple keywords; earlier array items have higher priority. Options / constraints: input_price, output_price, throughput, latency, input_length. |
extra_body.provider.input_price_range | [number, number] | No | — | Limits the current account's input price range. Options / constraints: Unit: USD / million tokens; range=[] is illegal. |
extra_body.provider.output_price_range | [number, number] | No | — | Limits the current account's output price range. Options / constraints: Unit: USD per million tokens; the range must contain exactly two nonnegative values and its lower bound must not exceed its upper bound. |
extra_body.provider.throughput_range | [number, number] | No | — | Limits the real-time throughput range. Options / constraints: Unit: tokens/s. |
extra_body.provider.latency_range | [number, number] | No | — | Limits the real-time latency range. Options / constraints: Unit: seconds. |
extra_body.provider.input_length_range | [number, number] | No | — | Limits the range of maximum input lengths supported by providers. Options / constraints: Unit: tokens. |
extra_body.provider.allow_fallbacks | boolean | No | — | Defaults to false when only is non-empty; otherwise defaults to true. Options / constraints: Finally, when there is no channel, HTTP 503 / no_available_provider is returned. |
Returns results in descending relevance order and includes information about the provider that served the request.
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
model | string | No | — | Model ID actually used for this request. |
results | array | No | — | Reranked results, usually ordered from highest to lowest relevance_score. |
results[].index | integer | No | — | Document position in the original documents list. |
results[].relevance_score | number | No | — | Relevance score. Higher values generally indicate greater relevance. Compare scores only within the same model and task. |
usage.prompt_tokens | integer | No | — | The number of tokens for the input query and candidate documents when the protocol returns. |
usage.total_tokens | integer | No | — | The total number of tokens counted in this call. |
provider | string | No | — | Information about the service provider channel that actually carries the request. Options / constraints: May only appear in non-streaming JSON. |
First retrieve a candidate set with keyword or vector search, then submit query and documents for reranking. Use top_n to control how many documents enter the downstream context.
relevance_score is a model relevance signal, not a guarantee of factual accuracy. Evaluate it together with a threshold, source permissions, document freshness, and the final generation model.
Record query, candidate-document count, top_n, and request ID on the server. Pass only documents that meet both permission filters and the relevance threshold to the downstream generation model.
The examples use placeholders. Replace them with a currently available model ID from the model details page, and keep your API Key in a server-side environment variable.
curl https://api.tokensmarket.ai/v1/rerank \
-H "Authorization: Bearer $TOKEN_MARKET_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<MODEL_ID>",
"query": "What is machine learning?",
"documents": [
"Machine learning enables computers to learn from data.",
"Deep learning is a subset of machine learning.",
"Python is commonly used for data science."
],
"top_n": 2,
"extra_body": {
"provider": {"sort": ["throughput"]}
}
}'