> ## Documentation Index > Fetch the complete documentation index at: https://docs.conare.ai/llms.txt > Use this file to discover all available pages before exploring further. # Rerank documents > Rerank 1-64 caller-owned candidates with the same configured retrieval reranker used by Conare search. Candidates are scored and returned; nothing is stored and no `endUserId` is involved. - `model` is a pin, not a selector. A name other than the one returned by the endpoint fails with `400 model_not_served`. - The memory plane enforces an 80 ms direct-rerank budget and reports measured provider and total compute in `_timing`. Network time to the Conare edge remains visible to the caller's own wall clock. - Candidate IDs must be unique and are returned verbatim with both the original input index and the reranker score. ## OpenAPI ````yaml /api/openapi.yaml post /api/v1/rerank openapi: 3.1.0 info: title: Conare API version: 1.3.0 summary: Per-end-user memory and connected-app actions for AI applications. description: > The Conare API gives your application a persistent, personalized memory layer. Production applications authenticate as an organization-owned Integration. Every request names an `endUserId`, and that end user's memory lives in its own isolated ConareDB namespace. The physical tenant is an opaque HMAC derived from the Integration and end-user ID; clients cannot select namespaces or address another tenant. On top of storage the API provides hybrid retrieval (vector + BM25, fused and reranked, sub-second), LLM-synthesized **deep recall**, **proactive suggestions** grounded in a user's memory, and explicitly scoped, idempotent writes through an end user's connected apps. Authentication normally uses a scoped server-side Integration Bearer key (`cint_...`). The secret is shown once and persisted by Conare only as a SHA-256 digest. Keep it in a server-side secret manager; never ship it to the browser. Legacy personal `cmem_...` keys remain accepted during migration. The stateless embeddings endpoint also accepts the platform key (`sk-conare-...`) that ConareDB accepts directly. A search service can use that one bearer for both embedding and database requests. Every response includes `X-Request-Id`. Send a caller-generated safe value (1–128 characters; first alphanumeric, then `A-Za-z0-9._:-`) to correlate one request through the Conare edge and memory plane; otherwise Conare generates one. Errors use a stable `{ statusCode, code, message, requestId, details? }` envelope and never include internal tenant IDs or backend error text. contact: name: Conare url: https://conare.ai email: artem@conare.ai servers: - url: https://api.conare.ai description: Production (dedicated partner-API host) - url: https://conare.ai description: Production (alias — same API, on the main host) security: - bearerAuth: [] tags: - name: Integration description: Credential, configuration, and backend readiness. - name: Memories description: Write and search a single end user's memory. - name: Recall description: LLM-synthesized personalization primitives. - name: Embeddings description: Embed text with Conare's own retrieval embedding model. - name: Reranking description: Rerank caller-owned candidates with Conare's live retrieval model. - name: Connectors description: >- Let end users sync ~200 data sources into memory and execute scoped writes through supported connected accounts. - name: Users description: End-user lifecycle (GDPR). paths: /api/v1/rerank: post: tags: - Reranking summary: Rerank documents description: | Rerank 1-64 caller-owned candidates with the same configured retrieval reranker used by Conare search. Candidates are scored and returned; nothing is stored and no `endUserId` is involved. - `model` is a pin, not a selector. A name other than the one returned by the endpoint fails with `400 model_not_served`. - The memory plane enforces an 80 ms direct-rerank budget and reports measured provider and total compute in `_timing`. Network time to the Conare edge remains visible to the caller's own wall clock. - Candidate IDs must be unique and are returned verbatim with both the original input index and the reranker score. operationId: rerankDocuments requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/RerankRequest' examples: default: value: query: How do I cancel a running agent safely? documents: - id: docs:checkpointing text: Persist the checkpoint before cancelling the run. - id: web:interrupts text: Cancellation interrupts execution immediately. limit: 2 responses: '200': description: Candidates ordered by descending reranker score. content: application/json: schema: $ref: '#/components/schemas/RerankResponse' '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '502': $ref: '#/components/responses/BadGateway' '503': $ref: '#/components/responses/ServiceUnavailable' '504': $ref: '#/components/responses/GatewayTimeout' components: schemas: RerankRequest: type: object required: - query - documents properties: query: type: string minLength: 1 maxLength: 8192 documents: type: array minItems: 1 maxItems: 64 items: $ref: '#/components/schemas/RerankDocument' limit: type: integer minimum: 1 maximum: 64 description: >- Results to return; defaults to the document count and cannot exceed it. model: type: string minLength: 1 description: Optional serving-model pin; any non-serving name fails loudly. RerankResponse: type: object required: - success - model - provider - results - _timing - usage properties: success: type: boolean model: type: string provider: type: string results: type: array items: $ref: '#/components/schemas/RerankResult' _timing: type: object required: - providerMs - totalMs - candidateCount - resultCount - budgetMs - budgetPassed properties: providerMs: type: integer totalMs: type: integer candidateCount: type: integer resultCount: type: integer budgetMs: type: integer example: 80 budgetPassed: type: boolean usage: type: object required: - totalChars - approxInputTokens properties: totalChars: type: integer approxInputTokens: type: integer RerankDocument: type: object required: - id - text properties: id: type: string minLength: 1 maxLength: 256 description: Caller-owned unique candidate identifier. text: type: string minLength: 1 maxLength: 24000 description: Candidate text passed to the retrieval reranker. RerankResult: type: object required: - id - index - score properties: id: type: string index: type: integer minimum: 0 description: Position in the request's documents array. score: type: number Error: type: object properties: statusCode: type: integer code: type: string description: Stable snake_case machine error code. message: type: string requestId: type: string description: Correlates this response through Conare services and logs. details: type: object additionalProperties: true required: - statusCode - code - message - requestId responses: BadRequest: description: Missing or invalid fields (e.g. bad `endUserId`, empty `query`). content: application/json: schema: $ref: '#/components/schemas/Error' Unauthorized: description: Missing or invalid Bearer key. content: application/json: schema: $ref: '#/components/schemas/Error' Forbidden: description: >- The Integration credential does not include the required operation scope. content: application/json: schema: $ref: '#/components/schemas/Error' BadGateway: description: The configured reranker failed. content: application/json: schema: $ref: '#/components/schemas/Error' ServiceUnavailable: description: Integration namespace routing or the memory backend is not ready. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/Error' GatewayTimeout: description: The configured reranker exceeded the direct API latency budget. content: application/json: schema: $ref: '#/components/schemas/Error' headers: RequestId: description: Caller-provided or generated request correlation identifier. schema: type: string securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: cint_ description: | A scoped Integration key, prefixed `cint_`. Send as `Authorization: Bearer cint_...` on every request. Server-side only. Legacy personal `cmem_...` keys remain accepted during migration; team/org-scoped `cmem_...` keys are not valid on this API. ````