> For the complete documentation index, see [llms.txt](https://docs.ionos.com/cloud/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ionos.com/cloud/api-reference/ai/ai-model-hub/open-ai-compatible-endpoints/rerank-documents-by-relevance-to-a-query.md).

# Rerank documents by relevance to a query

Rerank a list of documents by their relevance to a given query. Returns the documents sorted by relevance score in descending order. Supports both text-only documents (as strings) and multimodal documents (as objects with a `content` array) for compatible models.

```json
{"openapi":"3.0.3","info":{"title":"IONOS CLOUD - OpenAI compatible AI Model Hub API","version":"1.0.0"},"tags":[{"name":"OpenAI Compatible Endpoints","description":"Endpoints compatible with OpenAI's API specification"}],"servers":[{"url":"https://openai.inference.de-txl.ionos.com","description":"Berlin"}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Please provide header value as 'Bearer <token>' and don't forget to add 'Bearer' HTTP Authorization Scheme before the token."}},"schemas":{"RerankRequest":{"type":"object","properties":{"model":{"type":"string","description":"ID of the model to use"},"query":{"type":"string","description":"The query to rank documents against"},"documents":{"oneOf":[{"type":"array","description":"A list of documents as plain text strings","minItems":1,"items":{"type":"string"}},{"type":"array","description":"A list of multimodal documents","minItems":1,"items":{"type":"object","properties":{"content":{"type":"array","description":"Content parts of the document (text, images, etc.)","items":{"oneOf":[{"$ref":"#/components/schemas/ChatCompletionContentPartText"},{"$ref":"#/components/schemas/ChatCompletionContentPartImage"}]}}},"required":["content"]}}],"description":"The documents to be ranked against the query. Can be a list of strings for text-only models, or a list of objects with a content array for multimodal models.\n"},"top_n":{"type":"integer","description":"Number of top results to return. 0 or omitted means return all documents.","default":0,"minimum":0}},"required":["model","query","documents"]},"ChatCompletionContentPartText":{"type":"object","description":"Text content part","properties":{"type":{"type":"string","enum":["text"],"description":"The type of the content part"},"text":{"type":"string","description":"The text content"}},"required":["type","text"]},"ChatCompletionContentPartImage":{"type":"object","description":"Image content part","properties":{"type":{"type":"string","enum":["image_url"],"description":"The type of the content part"},"image_url":{"$ref":"#/components/schemas/ChatCompletionContentPartImageImageUrl"}},"required":["type","image_url"]},"ChatCompletionContentPartImageImageUrl":{"type":"object","description":"Image URL or data","properties":{"url":{"type":"string","description":"Either a URL of the image or the base64 encoded image data.\nSupported formats:\n- URLs: https://example.com/image.jpg\n- Base64 data URLs: data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAAAQ...\n"},"detail":{"type":"string","description":"Specifies the detail level of the image. \n- \"low\" uses fewer tokens and is faster\n- \"high\" is more detailed but uses more tokens\n- \"auto\" lets the model choose\n","enum":["low","high","auto"],"default":"auto"}},"required":["url"]},"RerankResponse":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the rerank request"},"model":{"type":"string","description":"Model name used for reranking"},"results":{"type":"array","description":"Results sorted by relevance score in descending order","items":{"$ref":"#/components/schemas/RerankResult"}},"usage":{"$ref":"#/components/schemas/RerankUsage"}}},"RerankResult":{"type":"object","properties":{"index":{"type":"integer","description":"Original index of this document in the input array"},"document":{"description":"The echoed document. Text documents are returned as an object with a `text` field; multimodal documents are returned as an object with a `content` array.","oneOf":[{"type":"object","properties":{"text":{"type":"string","description":"The document text (for plain-text inputs)"}}},{"type":"object","properties":{"content":{"type":"array","description":"Content parts of the document (for multimodal inputs)","items":{"oneOf":[{"$ref":"#/components/schemas/ChatCompletionContentPartText"},{"$ref":"#/components/schemas/ChatCompletionContentPartImage"}]}}}}]},"relevance_score":{"type":"number","format":"float","description":"Relevance score (typically 0.0 to 1.0)"}}},"RerankUsage":{"type":"object","properties":{"prompt_tokens":{"type":"integer","description":"Number of prompt tokens processed"},"total_tokens":{"type":"integer","description":"Total tokens processed"}}},"ErrorResponse":{"type":"object","description":"OpenAI-compatible error response. Returned for error responses that define this schema (for example, 429 Too Many Requests). Note: the backend currently returns an IONOS-native error body format; alignment to this schema is tracked in GPHML-2078.\n","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Human-readable error description."},"type":{"type":"string","description":"Error category (e.g. \"requests\", \"invalid_request_error\")."},"code":{"type":"string","nullable":true,"description":"Machine-readable error code (e.g. \"rate_limit_exceeded\"). May be null or omitted."},"param":{"type":"string","nullable":true,"description":"Parameter related to the error, if applicable. May be null or omitted."}},"required":["message","type"]}},"required":["error"]}},"headers":{"X-RateLimit-Limit":{"description":"Sustained request rate limit expressed as requests per minute. Enforcement is per second — see X-RateLimit-Burst for the short-window limit. The actual value depends on your contract; the default is 300 req/min (5 req/s).\n","schema":{"type":"integer"}},"X-RateLimit-Burst":{"description":"Maximum number of requests allowed within a 2-second burst window. Exceeding this triggers a 429 response. The actual value depends on your contract; the default is 10 requests per burst window.\n","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in the current 2-second burst window. Resets when the burst window expires. Does not reflect the per-minute X-RateLimit-Limit.\n","schema":{"type":"integer"}}},"responses":{"TooManyRequests":{"description":"Rate limit exceeded. Retry after the number of seconds indicated by the Retry-After header. Limits are contract-specific; check X-RateLimit-Limit and X-RateLimit-Burst in the response headers for the values that apply to your contract.\n","headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}},"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Burst":{"$ref":"#/components/headers/X-RateLimit-Burst"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"Overloaded":{"description":"The platform is temporarily overloaded and is shedding load to stay stable. Retry after the number of seconds indicated by the Retry-After header. This is unrelated to your contract's rate limits.\n","headers":{"Retry-After":{"description":"Number of seconds to wait before retrying.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"paths":{"/v1/rerank":{"post":{"operationId":"openaiCompatRerankPost","summary":"Rerank documents by relevance to a query","description":"Rerank a list of documents by their relevance to a given query.\nReturns the documents sorted by relevance score in descending order.\nSupports both text-only documents (as strings) and multimodal documents\n(as objects with a `content` array) for compatible models.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RerankRequest"}}}},"responses":{"200":{"description":"Successful operation","headers":{"X-RateLimit-Limit":{"$ref":"#/components/headers/X-RateLimit-Limit"},"X-RateLimit-Burst":{"$ref":"#/components/headers/X-RateLimit-Burst"},"X-RateLimit-Remaining":{"$ref":"#/components/headers/X-RateLimit-Remaining"}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RerankResponse"}}}},"400":{"description":"Bad request"},"429":{"$ref":"#/components/responses/TooManyRequests"},"500":{"description":"Server error"},"529":{"$ref":"#/components/responses/Overloaded"}},"tags":["OpenAI Compatible Endpoints"]}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ionos.com/cloud/api-reference/ai/ai-model-hub/open-ai-compatible-endpoints/rerank-documents-by-relevance-to-a-query.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.