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 | — | Reranker model ID from the Model Market. Model names are case-insensitive and the server normalizes them. Options / constraints: Use a currently available model ID from the model details page. |
query | string | Yes | — | Query text used for relevance comparison. |
documents | string[] | Yes | — | Candidate documents to rerank. First build the candidate set with keyword or vector retrieval. Options / constraints: Each item is a text passage to compare. |
top_n | integer | No | — | Returns only the N most relevant results. Options / constraints: Must be greater than 0; leave it blank to use the provider default or return all results. |
return_documents | boolean | No | true | Whether to include the document content corresponding to each index in the results. Options / constraints: true / false. |
extra_body | object | No | — | Extension field for unified-API routing, billing, and policy controls. Options / constraints: provider, consume_type. |
extra_body.provider | object | No | — | Provider selection, filtering, sorting, and metric ranges. Options / constraints: The platform applies filters in this order: only → ignore → range filters → order → sort. |
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: Returns 422 if the same provider appears in both only and ignore. |
extra_body.provider.order | string[] | No | — | Preferred provider order. 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 input-price range. Options / constraints: Unit: ¥ per 1M tokens. Example: [1, 2]. |
extra_body.provider.output_price_range | [number, number] | No | — | Limits the output-price range. Options / constraints: Unit: ¥ per 1M tokens. |
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.output_length_range | [number, number] | No | — | Limits the range of maximum output lengths supported by providers. Options / constraints: Unit: tokens. |
extra_body.provider.allow_filter_prompt_length | boolean | No | true | Whether to automatically filter providers by the input length for this request. Options / constraints: true / false. |
extra_body.provider.allow_fallbacks | boolean | No | true | Whether to fall back to other available channels according to the sort policy when no filter matches. Options / constraints: true / false. |
extra_body.enable_thinking | boolean | No | — | Reranker requests accept this field but ignore it. Options / constraints: true / false. |
extra_body.consume_type | string | No | api | Labels the purpose of this call for billing and request tracking. Options / constraints: chat or api. Use api for Reranker calls. |
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. |
results[].document | string | No | — | Corresponding document content. Options / constraints: Returned only when return_documents=true. The server normalizes object-shaped documents to strings. |
usage.prompt_tokens | integer | No | — | Number of tokens consumed by the input query and candidate documents. If the downstream provider omits this value, the platform may estimate it from the request content. |
usage.total_tokens | integer | No | — | Total number of tokens counted for this call. |
provider | string | No | — | Information about the provider channel that served the request. |
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,
"return_documents": true,
"extra_body": {
"provider": {"sort": ["throughput"]},
"consume_type": "api"
}
}'