> ## Documentation Index > Fetch the complete documentation index at: https://docs.playapi.ai/llms.txt > Use this file to discover all available pages before exploring further. # Rerank documents > Request parameters, responses, and channel compatibility. `POST /v1/rerank` Send JSON with `model`, a nonempty `query`, and candidate `documents`. Explicitly set `top_n` and `return_documents` and consult the guide for channel differences; unchanged forwarding is not guaranteed. `results[].index` points to the original input array, and `relevance_score` is a model-dependent ranking score. The shape and availability of `document` and `usage` depend on the channel. Allow extra fields and do not depend on returned source text. This endpoint only ranks supplied candidates; it does not generate vectors or answers. [Guide and runnable example](/en/guides/rerank) [简体中文](/zh/api-reference/rerank) ## OpenAPI ````yaml openapi/relay.json POST /v1/rerank openapi: 3.0.3 info: title: API — Core inference API version: 0.5.0 description: >- 面向接入的精选规范，不是全部管理或供应商接口。 / Curated integration specification, not the entire management or provider API. license: name: AGPL-3.0-or-later servers: - url: https://gateway.example.com description: >- Example only; replace with your gateway origin and optional path prefix, without /v1. security: - BearerAuth: [] paths: /v1/rerank: post: summary: 重排候选文档 / Rerank candidate documents description: >- 同步 JSON 接口，模型和渠道决定可选参数支持情况 / Synchronous JSON endpoint; model and channel determine optional parameter support operationId: rerankDocuments requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RerankRequest' responses: '200': description: >- 成功结构；仍需校验索引与实际数值，示例向量维度和分数仅作结构演示 / Success shape; validate indices and values; example vector dimensions and scores are illustrative content: application/json: schema: $ref: '#/components/schemas/RerankResult' example: results: - index: 1 relevance_score: 0.91 - index: 0 relevance_score: 0.12 '400': description: 请求参数错误 / Invalid request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: 身份校验失败 / Authentication failed content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: 访问被拒绝 / Access denied content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: 接口或资源不存在 / Endpoint or resource not found content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: 请求被限流或受配额限制 / Rate or quota restriction content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: 网关或上游错误 / Gateway or upstream error content: application/json: schema: $ref: '#/components/schemas/Error' '503': description: 服务暂不可用 / Service unavailable content: application/json: schema: $ref: '#/components/schemas/Error' default: description: 其他网关或上游错误；格式可能不同 / Other gateway or upstream error; shape may vary content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: RerankRequest: type: object properties: model: type: string description: >- 支持此接口且当前密钥可用的模型 / Model available to this key and supporting this endpoint example: YOUR_MODEL_ID query: type: string description: 非空查询文本 / Nonempty query text minLength: 1 documents: type: array description: >- 非空候选列表；优先字符串，对象字段由渠道决定 / Nonempty candidates; prefer strings, object fields depend on channel minItems: 1 items: oneOf: - type: string minLength: 1 - type: object additionalProperties: true top_n: type: integer description: >- 建议正整数且不超过候选数；Cohere 省略或非正数时转为 1，其他渠道默认不同 / Use a positive count no larger than candidates; Cohere maps omitted/nonpositive to 1, other defaults differ minimum: 1 return_documents: type: boolean description: >- 请求回传原文；Cohere 强制 true，Ali 省略时默认 true；不能作为通用不回传保证 / Request source text; Cohere forces true, Ali defaults to true when omitted; not a universal suppression guarantee max_chunk_per_doc: type: integer description: >- 可选渠道参数；注意单数拼写，部分适配器不转发 / Optional channel parameter; singular spelling, not forwarded by all adaptors overlap_tokens: type: integer description: >- 可选分块重叠参数；支持情况由渠道决定 / Optional chunk overlap; support depends on channel required: - model - query - documents RerankResult: type: object properties: results: type: array description: 候选的相关性结果；可为空 / Candidate relevance results; may be empty items: type: object properties: index: type: integer description: >- 本次 documents 的零基索引，不是排名或业务 ID / Zero-based position in this request's documents, not rank or application ID minimum: 0 relevance_score: type: number description: >- 分数越高越相关；没有全渠道统一的范围或概率含义 / Higher scores indicate greater relevance; no universal range or probability interpretation document: description: >- 可选原文；可能为字符串或包含 text 的对象，不保证返回 / Optional source, possibly a string or object containing text; not guaranteed nullable: true anyOf: - type: string - type: object additionalProperties: true required: - index - relevance_score usage: type: object properties: prompt_tokens: type: integer total_tokens: type: integer required: - results Error: type: object properties: error: type: object properties: message: type: string type: type: string param: type: string nullable: true code: nullable: true description: 错误标识；类型随上游变化 / Error identifier; type varies by upstream securitySchemes: BearerAuth: type: http scheme: bearer description: 模型调用 API Key，不是控制台登录凭据 / Model API key, not console login credentials ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.