> ## Documentation Index > Fetch the complete documentation index at: https://docs.naga.ac/llms.txt > Use this file to discover all available pages before exploring further. # Rerank documents > Ranks documents by their relevance to a query and charges the account for the tokens the model read. Requires an API key. ## OpenAPI ````yaml /openapi/naga-api.json post /v1/rerank openapi: 3.1.0 info: title: NagaAI API description: >- NagaAI routes inference requests to a pool of upstream providers behind one endpoint. Requests speak the OpenAI or the Anthropic dialect, and the gateway selects a provider that serves the requested model. Two credentials exist and they are not interchangeable. An API key reaches models. A provisioning key manages the account: its keys, its balance, and its usage. Each operation declares which one it accepts. NagaAI charges the account in credits for the tokens a request consumes, at the published price of the model that served it. One credit costs one US dollar. termsOfService: https://naga.ac/legal/terms contact: name: NagaAI url: https://naga.ac version: '2026-03-31' summary: >- One API to many model providers, in the OpenAI and Anthropic request formats. servers: - url: https://api.naga.ac description: Production security: [] tags: - name: Chat Completions description: >- The OpenAI Chat Completions dialect, with streaming, tools and multimodal input. externalDocs: url: https://platform.openai.com/docs/api-reference/chat description: The OpenAI reference for this dialect. - name: Messages description: >- The Anthropic Messages dialect, as Claude-style clients and agents speak it. externalDocs: url: https://docs.anthropic.com/en/api/messages description: The Anthropic reference for this dialect. - name: Responses description: >- The OpenAI Responses dialect, with structured input, tools and streamed output items. externalDocs: url: https://platform.openai.com/docs/api-reference/responses description: The OpenAI reference for this dialect. - name: Embeddings description: Vector embeddings for search, retrieval, clustering and ranking. externalDocs: url: https://platform.openai.com/docs/api-reference/embeddings description: The OpenAI reference for this route. - name: Images description: Image generation and editing with multimodal models. externalDocs: url: https://platform.openai.com/docs/api-reference/images description: The OpenAI reference for these routes. - name: Audio description: Speech from text, and text from uploaded audio. externalDocs: url: https://platform.openai.com/docs/api-reference/audio description: The OpenAI reference for these routes. - name: Videos description: 'Video generation as a job: submit it, poll it, download the file.' externalDocs: url: https://docs.naga.ac/api/videos description: The NagaAI guide to video generation. - name: Requests description: >- One request your key made, read back by its id: model, usage, cost and timing. externalDocs: url: https://docs.naga.ac/build/billing description: The NagaAI guide to billing. - name: Moderations description: Safety classification of text and image input. externalDocs: url: https://platform.openai.com/docs/api-reference/moderations description: The OpenAI reference for this route. - name: Rerank description: Documents ordered by relevance to a query, for search and retrieval. externalDocs: url: https://docs.naga.ac/guides/rerank description: The NagaAI guide to reranking. - name: Models description: The catalog of models, their capabilities and their prices. externalDocs: url: https://platform.openai.com/docs/api-reference/models description: The OpenAI reference for this route. - name: Startups description: The organizations whose models the catalog carries. externalDocs: url: https://docs.naga.ac/get-started/models description: The NagaAI guide to the model catalog. - name: Account description: The account's balance and its usage, behind a provisioning key. externalDocs: url: https://docs.naga.ac/account/balance-and-activity description: The NagaAI guide to balance and activity. - name: API Keys description: The account's API keys, behind a provisioning key. externalDocs: url: https://docs.naga.ac/account/api-keys description: The NagaAI guide to API keys. paths: /v1/rerank: post: tags: - Rerank summary: Rerank documents description: >- Ranks documents by their relevance to a query and charges the account for the tokens the model read. Requires an API key. operationId: create_rerank requestBody: content: application/json: schema: $ref: '#/components/schemas/Rerank' examples: basic: summary: Rank three documents, keep the best two value: model: qwen/qwen3-reranker-8b query: How do I rotate an API key? documents: - >- Create a new key, switch your clients to it, then revoke the old one. - The balance is shown in US dollars. - Keys can be limited to a monthly budget. top_n: 2 required: true responses: '200': description: >- The ranking. `results` carries the documents most relevant first, each with its index in the request and its score; `usage` carries the token count behind the charge. content: application/json: schema: $ref: '#/components/schemas/RerankResponse' examples: basic: summary: Two results, best first value: id: rrk-4tKq7Zc1Nb9Wx2Ry8Vd3Ms6Ph0Q model: qwen/qwen3-reranker-8b results: - index: 0 relevance_score: 0.9812 document: text: >- Create a new key, switch your clients to it, then revoke the old one. - index: 2 relevance_score: 0.1436 document: text: Keys can be limited to a monthly budget. usage: total_tokens: 61 x-retry-safe: false '400': description: >- The request is malformed: a field failed its constraint, the body is not valid JSON, or the model name is unknown. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' x-retry-safe: false '401': description: >- The API key is missing, malformed, disabled, or does not belong to an account that may call this route. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: invalid-api-key: summary: 401 — the key is not one this gateway serves value: error: type: invalid_api_key message: >- The provided API key is invalid. Please ensure your API key is correct and active. You can find more information about obtaining a key on our website: https://naga.ac If you just created this key, wait a few minutes and try again. x-retry-safe: false '402': description: The account has run out of credits. Top up the balance and retry. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: insufficient-credits: summary: 402 — the account has no credits left value: error: type: insufficient_quota message: >- More credits required to process this request. Visit https://naga.ac/dashboard/credits to add credits. x-retry-safe: false '403': description: >- The model policy of the organization or of the key's workspace does not allow this model, a spending limit is reached, or the content was blocked by the moderation policy. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' x-retry-safe: false '408': description: >- The request body did not finish arriving within 15 minutes, or stalled for 60 seconds. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' x-retry-safe: true '410': description: The model is deprecated and no longer served. Pick a current one. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' x-retry-safe: false '413': description: The request body is larger than the 32 MiB this gateway accepts. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' x-retry-safe: false '422': description: >- The request was understood but its usage could not be metered, so it was not served. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' x-retry-safe: false '429': description: >- The account exceeded its rate limit. `Retry-After` carries the wait in seconds. headers: Retry-After: schema: type: string description: How long to wait before retrying, in seconds. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' examples: rate-limited: summary: 429 — too many requests; `Retry-After` carries the wait value: error: type: rate_limit_exceeded message: >- Free model limit reached (100 requests per day and 10 per minute). Try again in 3s, or add credits at https://naga.ac/dashboard/credits to use paid models, which have no request limit. x-retry-safe: true '500': description: >- The gateway failed for a reason of its own. Report it — this status marks NagaAI's own bugs, never an upstream verdict. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' x-retry-safe: true '503': description: >- No upstream is available, or the gateway is shedding load. `Retry-After` carries the suggested wait. headers: Retry-After: schema: type: string description: How long to wait before retrying, in seconds. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' x-retry-safe: true security: - bearerAuth: [] - xApiKeyAuth: [] x-codeSamples: - lang: bash label: curl source: |- curl https://api.naga.ac/v1/rerank \ -H "Authorization: Bearer $NAGA_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "qwen/qwen3-reranker-8b", "query": "How do I rotate an API key?", "documents": [ "Create a new key, switch your clients to it, then revoke the old one.", "The balance is shown in US dollars.", "Keys can be limited to a monthly budget." ], "top_n": 2 }' components: schemas: Rerank: type: object description: The request body of `POST /v1/rerank`. required: - model - query - documents properties: model: type: string description: The rerank model, named by its id or alias. models: type: - array - 'null' items: type: string description: >- Fallback models, tried in order when `model` cannot answer: none of its providers served it. At most 3, and only the model that answered is billed. A NagaAI extension in OpenRouter's shape. maxItems: 3 routing: oneOf: - allOf: - $ref: '#/components/schemas/PriceRouting' description: >- How NagaAI picks the providers for this request: `max_price` removes the ones above it and can fail the request. A NagaAI extension. - type: 'null' query: type: string description: The search query the documents are ranked against. documents: type: array items: $ref: '#/components/schemas/RerankDocument' description: >- The documents to rank, from 1 to 1000: strings, or objects with `text`. maxItems: 1000 minItems: 1 top_n: type: - integer - 'null' format: int64 description: >- How many of the most relevant documents to return. All of them when absent. minimum: 1 return_documents: type: boolean description: Whether each result carries its document's text. `true` when absent. default: true RerankResponse: type: object description: The body of a successful `POST /v1/rerank`. required: - id - model - results - usage properties: id: type: string description: The identifier of this rerank, minted by the gateway. model: type: string description: The model that ranked, as the catalog id the request resolved to. results: type: array items: $ref: '#/components/schemas/RerankResult' description: The documents, most relevant first, cut to `top_n`. usage: allOf: - $ref: '#/components/schemas/RerankUsage' description: What the request was billed on. ErrorEnvelope: type: object description: >- `{"error": {…}}` — the body of every non-2xx answer outside `/v1/messages`. required: - error properties: error: allOf: - $ref: '#/components/schemas/ErrorBody' description: The failure itself, and the envelope's only member. PriceRouting: type: object description: >- Routing preferences of an image, video, audio, embeddings or moderation request. An unknown key inside draws a 400. A NagaAI extension. properties: max_price: type: - object - 'null' description: >- The most this request may pay per unit, keyed by a `meter` of the model's `pricing` in `GET /v1/models`: `{"output_image_token": "0.00003"}` caps image output at 30 credits per million tokens, `{"output_video_second": "0.1"}` caps a video at 0.1 credits per second. NagaAI then sends the request only to providers whose price for each named meter is at or below the cap, and a model whose price is above it is not tried. A meter the model does not price is ignored. An unknown meter or a negative value draws a 400. additionalProperties: $ref: '#/components/schemas/PriceCap' propertyNames: type: string additionalProperties: false RerankDocument: oneOf: - type: string title: Plain text - allOf: - $ref: '#/components/schemas/RerankDocumentObject' title: Document object description: 'One document to rank: plain text, or an object carrying it.' RerankResult: type: object description: One ranked document. required: - index - relevance_score properties: index: type: integer format: int64 description: The position of the document in the request's `documents`, from 0. relevance_score: type: number format: double description: >- How relevant the document is to the query; higher is more relevant. The scale is the model's own, so compare scores within one model only. document: oneOf: - allOf: - $ref: '#/components/schemas/RerankResultDocument' description: >- The document itself, unless the request set `return_documents` to `false`. - type: 'null' RerankUsage: type: object description: What the request was billed on. required: - total_tokens properties: total_tokens: type: integer format: int64 description: >- The tokens the model read: the query once beside each document, plus the documents. search_units: type: - integer - 'null' format: int64 description: >- The search units the request was billed, for a model sold per search: one query over up to 100 documents, a document past 500 tokens with the query counting once per 500-token chunk. ErrorBody: type: object description: 'The `error` member: what went wrong, in the caller''s terms.' required: - type - message properties: type: type: string description: >- The class of the failure; a provider's own class can reach you unchanged. examples: - invalid_request_error - authentication_required - invalid_api_key - invalid_provisioning_key - invalid_session_token - disabled_api_key - disabled_provisioning_key - expired_api_key - credit_limit_exceeded - rate_limit_exceeded - model_deprecated - inappropriate_content - billing_metering_incomplete - billing_request_id_invalid - billing_writer_missing - server_error message: type: string description: The human-readable sentence shown to the caller. code: type: - string - 'null' description: The finer-grained code, when the failure has one. param: type: - string - 'null' description: The request field the failure is about, when it is about one. PriceCap: oneOf: - type: string description: A decimal string, such as `"0.000004"`. - type: number format: double description: A JSON number, such as `0.000004`. description: 'A price cap: credits per unit, as a decimal string or a JSON number.' RerankDocumentObject: type: object description: A document given as an object. required: - text properties: text: type: string description: The document text. additionalProperties: false RerankResultDocument: type: object description: The text of a ranked document, echoed from the request. required: - text properties: text: type: string description: The document text, as the request sent it. securitySchemes: bearerAuth: type: http scheme: bearer description: 'An account API key. Send it as `Authorization: Bearer `.' xApiKeyAuth: type: apiKey in: header name: x-api-key description: >- An account API key. Send it as `x-api-key: `, the header Anthropic-style clients use. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.