> For the complete documentation index, see [llms.txt](https://docs.cortecs.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cortecs.ai/api/rerank.md).

# Rerank

## Rerank documents

> Returns relevance scores and the original document indexes. Text-only models accept text documents. Image documents support a multimodal reranker and a provider that supports the submitted format.

```json
{"openapi":"3.0.0","info":{"title":"Cortecs Rerank API","version":"1.0.0"},"servers":[{"url":"https://api.cortecs.ai/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"RerankRequest":{"type":"object","required":["model","query","documents"],"description":"A query and candidate documents to rerank. Additional provider parameters may be supplied, but unsupported parameters can cause a request to fail or restrict eligible providers.","additionalProperties":true,"properties":{"model":{"type":"string","description":"Choose an available model tagged Rerank."},"query":{"type":"string","description":"The query against which documents are scored."},"documents":{"type":"array","minItems":1,"description":"Candidate documents. Use strings for text-only models. Structured documents, including image content, require a compatible model and provider-specific document format.","items":{"oneOf":[{"type":"string"},{"type":"object","additionalProperties":true}]}},"top_n":{"type":"integer","minimum":1,"description":"The maximum number of ranked results to return. This does not limit the submitted documents processed by the reranker."},"return_documents":{"type":"boolean","nullable":true,"description":"Request document content in the results. Support and returned document fields depend on the provider."},"preference":{"type":"string","description":"The provider preference for handling the request.","enum":["speed","cost","balanced"]},"allowed_providers":{"type":"array","items":{"type":"string"},"description":"Provider IDs allowed to process the request, subject to project settings.","nullable":true},"eu_native":{"type":"boolean","description":"Whether to use only providers based and regulated within the EU.","nullable":true},"provider_order":{"type":"string","description":"Set to `custom` to try `allowed_providers` in the listed order instead of using preference-based routing.","enum":["custom"],"nullable":true},"quantizations":{"type":"array","items":{"type":"string","enum":["int4","int8","fp4","mxfp4","nvfp4","fp6","fp8","mxfp8","fp16","bf16","fp32","unknown"]},"description":"Allowed endpoint quantizations. fp4 and fp8 include their variants; unknown matches unspecified quantization.","nullable":true},"allow_quantization":{"type":"boolean","description":"Deprecated. Use `quantizations` instead. When false, excludes quantized endpoints.","deprecated":true,"nullable":true},"allow_zero_data_retention":{"type":"boolean","description":"Whether to use only zero-data-retention providers.","nullable":true},"require_model_presets":{"type":"boolean","description":"Require a project preset alias for all model requests.","nullable":true},"enable_model_fallback":{"type":"boolean","description":"Allow automatic model fallback. Project settings may override this value.","nullable":true},"fallbacks":{"type":"array","items":{"type":"string"},"description":"Explicit fallback model IDs, tried in order. A nonempty list takes precedence over automatic fallback settings.","nullable":true}}},"RerankResponse":{"type":"object","required":["results","usage"],"properties":{"id":{"type":"string","nullable":true,"description":"Request identifier, when supplied by the provider."},"results":{"type":"array","description":"Results ordered by relevance, with indexes referring to the original documents array.","items":{"$ref":"#/components/schemas/RerankResult"}},"usage":{"$ref":"#/components/schemas/Usage"}}},"RerankResult":{"type":"object","required":["index","relevance_score"],"properties":{"index":{"type":"integer","minimum":0,"description":"Zero-based position in the original documents array."},"relevance_score":{"type":"number","description":"Relevance score. Higher values indicate greater relevance; score scales depend on the model."},"document":{"type":"object","nullable":true,"additionalProperties":true,"description":"Document content, when returned by the provider.","properties":{"text":{"type":"string"}}}}},"Usage":{"type":"object","required":["prompt_tokens","completion_tokens","total_tokens"],"properties":{"prompt_tokens":{"type":"integer","minimum":0,"description":"Input tokens reported for reranking the query and candidate documents."},"completion_tokens":{"type":"integer","enum":[0],"description":"Rerank requests do not generate completion tokens."},"total_tokens":{"type":"integer","minimum":0,"description":"Equal to prompt_tokens for rerank requests."},"cost":{"type":"number","minimum":0,"description":"Calculated cost in the unit selected by `x-cortecs-cost-unit` (credits by default; 1,000,000 credits = €1)."}}}}},"paths":{"/rerank":{"post":{"parameters":[{"in":"header","name":"x-cortecs-cost-unit","description":"Unit for returned usage cost values. Defaults to CREDITS (1,000,000 credits = €1); EUR and USD select currency amounts.","required":false,"schema":{"type":"string","enum":["CREDITS","EUR","USD"],"default":"CREDITS"}}],"summary":"Rerank documents","description":"Returns relevance scores and the original document indexes. Text-only models accept text documents. Image documents support a multimodal reranker and a provider that supports the submitted format.","operationId":"createRerank","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RerankRequest"}}}},"responses":{"200":{"description":"Ranked documents and input-token usage.","headers":{},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RerankResponse"}}}},"400":{"description":"Invalid request or a document format unsupported by the selected model or provider."},"500":{"description":"Internal server error."}}}}}}
```
