> ## Documentation Index > Fetch the complete documentation index at: https://docs.prisme.ai/llms.txt > Use this file to discover all available pages before exploring further. # Rerank documents by relevance > Reranks a set of candidate documents by their relevance to a query, following the de-facto standard rerank contract (compatible with Cohere v2 / Jina / Voyage): a request of `{ model, query, documents }` returns `{ results: [{ index, relevance_score }] }` sorted by `relevance_score` descending, where `index` is the position of the document in the input `documents` array. **Backend.** LLM-as-reranker: relevance is scored via chat completions (deterministic, `temperature: 0`, JSON output), then sorted server-side so the ordering never relies on the model's own output order. The request/response contract deliberately matches native rerankers, so the backend can later be swapped to a native cross-encoder without changing callers. Use `model: "mock"` for a deterministic, LLM-free response in CI / load tests. **Limits.** All documents are scored in a single prompt (no batching); `documents` is capped at 200 items and `max_tokens_per_doc` is advisory. Suited to a post-retrieval rerank window rather than large corpora. **Rate limiting.** 100 requests per 60 seconds per consumer (`auth.user_id` or `session.id`). **Governance.** Reuses the `chat-completions` permission and the organization governance overlay, so calls may be rejected with `403 MODEL_NOT_ALLOWED` or `429` quota errors. ## OpenAPI ````yaml /api-reference/llm-gateway/swagger.yml post /v1/rerank openapi: 3.0.3 info: version: 1.0.0 title: LLM Gateway API description: | Public REST API for the Prisme.ai LLM Gateway - OpenAI-compatible chat completions and embeddings, plus a managed model catalogue with governance overrides per organization. The gateway abstracts multi-provider LLM access (OpenAI, Azure OpenAI, Anthropic, Google Vertex, AWS Bedrock, OpenAI-compatible providers) behind an OpenAI-compatible request/response shape. It enforces per-tenant governance (allowed models, default models, quotas) and emits analytics events (`analytics.llm.completion`) usable for cost and carbon reporting. This spec documents only the public REST surface (endpoints exposed via Prisme.ai workspace webhooks). Internal helpers (private automations prefixed with `_`) and load-test mocks are not part of the public contract. contact: name: Prisme.ai url: https://prisme.ai servers: - url: https://{host}/v2/workspaces/slug:llm-gateway/webhooks description: Prisme.ai workspace webhooks variables: host: default: api.studio.prisme.ai description: API host (override for self-hosted or sandbox) security: - BearerAuth: [] - OrgApiKeyAuth: [] tags: - name: Completions description: OpenAI-compatible chat completions (with optional SSE streaming). - name: Embeddings description: OpenAI-compatible text embeddings. - name: Rerank description: >- Rerank documents by relevance to a query (standard rerank contract, LLM-as-reranker backend). - name: Models description: Model catalogue (CRUD + bulk replace + governance-aware listing). - name: Defaults description: >- Resolved default models for completions / embeddings / image generation / file parsing. - name: Test description: Smoke-test reachability of a model through the gateway. paths: /v1/rerank: post: tags: - Rerank summary: Rerank documents by relevance description: | Reranks a set of candidate documents by their relevance to a query, following the de-facto standard rerank contract (compatible with Cohere v2 / Jina / Voyage): a request of `{ model, query, documents }` returns `{ results: [{ index, relevance_score }] }` sorted by `relevance_score` descending, where `index` is the position of the document in the input `documents` array. **Backend.** LLM-as-reranker: relevance is scored via chat completions (deterministic, `temperature: 0`, JSON output), then sorted server-side so the ordering never relies on the model's own output order. The request/response contract deliberately matches native rerankers, so the backend can later be swapped to a native cross-encoder without changing callers. Use `model: "mock"` for a deterministic, LLM-free response in CI / load tests. **Limits.** All documents are scored in a single prompt (no batching); `documents` is capped at 200 items and `max_tokens_per_doc` is advisory. Suited to a post-retrieval rerank window rather than large corpora. **Rate limiting.** 100 requests per 60 seconds per consumer (`auth.user_id` or `session.id`). **Governance.** Reuses the `chat-completions` permission and the organization governance overlay, so calls may be rejected with `403 MODEL_NOT_ALLOWED` or `429` quota errors. operationId: createRerank requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RerankRequest' responses: '200': description: >- Successful rerank response (results sorted by relevance_score descending). content: application/json: schema: $ref: '#/components/schemas/RerankResponse' '400': description: | Validation error: missing `query`, empty `documents`, or more than 200 documents. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid authentication. content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: | Model not allowed for this caller (governance overlay). `error.code` is typically `MODEL_NOT_ALLOWED`. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: | Rate limit exceeded (`code: RATE_LIMITED`, 100 req / 60 s per consumer) or governance quota exceeded. content: application/json: schema: $ref: '#/components/schemas/Error' '502': description: | The reranker backend failed or returned no parseable results (`code: RERANK_FAILED` or `RERANK_PARSE_FAILED`). content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: RerankRequest: type: object required: - query - documents properties: model: type: string maxLength: 256 description: | Reranker model id. Defaults to the gateway's configured completions default. Use `"mock"` for a deterministic, LLM-free response. query: type: string maxLength: 8192 description: The search query to rank the documents against. documents: type: array maxItems: 200 description: Candidate passages to rerank. items: type: string maxLength: 8192 top_n: type: integer description: | Limit the number of returned results. Defaults to all documents; a value of 0 or less is ignored (returns all). max_tokens_per_doc: type: integer description: | Accepted for contract compatibility with native rerankers. Currently advisory (not enforced). analytics_context: type: object description: '**Prisme.ai extension.** Caller-supplied analytics context.' additionalProperties: true RerankResponse: type: object required: - id - results properties: id: type: string description: Unique identifier for this rerank request. results: type: array description: Scored documents, sorted by `relevance_score` descending. items: $ref: '#/components/schemas/RerankResult' meta: type: object properties: model: type: string backend: type: string enum: - llm-as-reranker - mock billed_units: type: object properties: input_tokens: type: integer output_tokens: type: integer Error: type: object required: - error description: | Standard error envelope. `error` carries either a stable PascalCase identifier or a free-text label (legacy endpoints) - `code` is the canonical machine-readable identifier going forward. properties: error: type: string description: Stable PascalCase identifier or short error label. message: type: string description: Human-readable error message. code: type: string description: | Machine-readable error code. Observed values include `RATE_LIMITED`, `MODEL_NOT_ALLOWED`, `MODEL_NOT_FOUND`, `MODEL_EXISTS`, `MISSING_MODEL_ID`, `MISSING_TYPE`, `INVALID_BODY`, `INVALID_ITEMS`, `INVALID_DIMENSIONS`, `PAYLOAD_TOO_LARGE`, `METHOD_NOT_ALLOWED`, `PROVIDER_ERROR`, `PROVIDER_NO_RESPONSE`. details: description: Optional structured context (e.g. list of invalid items). additionalProperties: true status: type: integer description: HTTP status mirror, when present. retryAfter: type: integer description: Seconds to wait before retrying (rate-limit responses). provider: type: string description: Upstream provider name (provider-error responses). model: type: string description: Model id involved in the error (provider-error responses). provider_error_type: type: string description: Upstream provider's own error class name. RerankResult: type: object required: - index - relevance_score properties: index: type: integer description: Position of the document in the input `documents` array. relevance_score: type: number format: float description: Relevance of the document to the query, normalized to [0, 1]. securitySchemes: BearerAuth: type: http scheme: bearer bearerFormat: JWT description: | User-bound credential carrying an identity: either a session JWT or a user access token (`at:*`) generated from the user settings UI. Send as `Authorization: Bearer `. Org API keys (`iak_*`) are **not** accepted here - they carry no user identity. Use the `x-prismeai-api-key` header instead (see `OrgApiKeyAuth`). OrgApiKeyAuth: type: apiKey in: header name: x-prismeai-api-key description: | Organization API key (`iak_{orgSlug}_{uuid}`). Unlike `Authorization: Bearer`, this credential is **not** tied to a user identity - it is bound to the org and its effective access is defined by the scopes / permission rules attached to it (it can be restricted to a single project, or kept broader). Send as `x-prismeai-api-key: iak_...`. ````