> ## Documentation Index > Fetch the complete documentation index at: https://docs.isaacus.com/llms.txt > Use this file to discover all available pages before exploring further. # Reranking > Score and rank documents by their relevance to queries with an Isaacus reranker. ## OpenAPI ````yaml https://app.stainless.com/api/spec/documented/isaacus/openapi.documented.yml post /rerankings openapi: 3.1.0 info: title: Isaacus API version: 0.8.2 description: A RESTful API for using Isaacus legal models, data and other solutions. termsOfService: https://isaacus.com/terms contact: name: Isaacus Support url: https://isaacus.com/support email: support@isaacus.com license: name: Apache 2.0 url: https://github.com/isaacus-dev/openapi/blob/main/LICENSE servers: - url: https://api.isaacus.com/v1 security: - APIKeyBearerTokenAuth: [] tags: - name: Enrichments description: Enrich documents with an Isaacus enrichment model. - name: Embeddings description: Vectorize content with an Isaacus embedding model. - name: Rerankings description: >- Score and rank documents by their relevance to queries with an Isaacus reranker. - name: Extractions description: Extract information from documents with an Isaacus extraction model. - name: Classifications description: Classify documents with an Isaacus classification model. externalDocs: url: https://docs.isaacus.com/api-reference description: Reference documentation for the Isaacus API. paths: /rerankings: post: tags: - Rerankings summary: Reranking description: >- Score and rank documents by their relevance to queries with an Isaacus reranker. operationId: CreateReranking requestBody: content: application/json: schema: $ref: '#/components/schemas/RerankingRequest' required: true responses: '200': description: Request fulfilled, document follows headers: {} content: application/json: schema: $ref: '#/components/schemas/RerankingResponse' '400': description: The request was invalid or could not be processed. content: application/problem+json: schema: $ref: '#/components/schemas/ValidationError' examples: Validation error: summary: Validation error value: type: >- https://docs.isaacus.com/api-reference/errors#400-validation-error title: Validation error status: 400 detail: The request was invalid or could not be processed. instance: null Invalid IQL query error: summary: Invalid IQL query error value: type: >- https://docs.isaacus.com/api-reference/errors#400-validation-error title: Invalid IQL query error status: 400 detail: >- The provided query is not valid Isaacus Query Language (IQL) syntax. instance: null Query too long error: summary: Query too long error value: type: >- https://docs.isaacus.com/api-reference/errors#400-validation-error title: Query too long error status: 400 detail: >- The provided query exceeds the model's maximum input length less overhead. instance: null '401': description: >- The API key you provided does not exist, is expired or revoked, or is not authorized to access this resource. content: application/problem+json: schema: $ref: '#/components/schemas/UnauthorizedAPIKeyError' examples: Unauthorized API key error: summary: Unauthorized API key error value: type: >- https://docs.isaacus.com/api-reference/errors#401-not-authenticated title: Unauthorized API key error status: 401 detail: >- The API key you provided does not exist, is expired or revoked, or is not authorized to access this resource. instance: null Incorrect API key error: summary: Incorrect API key error value: type: >- https://docs.isaacus.com/api-reference/errors#401-not-authenticated title: Incorrect API key error status: 401 detail: >- The API key you provided does not exist or is expired or revoked. instance: null '402': description: >- Your account is overdue, please pay any outstanding invoices to continue using our services. content: application/problem+json: schema: $ref: '#/components/schemas/AccountOverdueError' examples: Account overdue error: summary: Account overdue error value: type: >- https://docs.isaacus.com/api-reference/errors#402-payment-required title: Account overdue error status: 402 detail: >- Your account is overdue, please pay any outstanding invoices to continue using our services. instance: null '403': description: You are not allowed to access this resource. content: application/problem+json: schema: $ref: '#/components/schemas/AccessForbiddenError' examples: Access forbidden error: summary: Access forbidden error value: type: >- https://docs.isaacus.com/api-reference/errors#403-access-forbidden title: Access forbidden error status: 403 detail: You are not allowed to access this resource. instance: null No subscription error: summary: No subscription error value: type: >- https://docs.isaacus.com/api-reference/errors#403-access-forbidden title: No subscription error status: 403 detail: >- You do not have an active subscription to our zero-flat fee, usage-based API plan. instance: null '413': description: The request is larger than the server is willing or able to process. content: application/problem+json: schema: $ref: '#/components/schemas/RequestTooLargeError' examples: Request too large error: summary: Request too large error value: type: >- https://docs.isaacus.com/api-reference/errors#413-request-too-large title: Request too large error status: 413 detail: >- The request is larger than the server is willing or able to process. instance: null '500': description: An unexpected error occurred while processing the request. content: application/problem+json: schema: $ref: '#/components/schemas/InternalServerError' examples: Internal server error: summary: Internal server error value: type: >- https://docs.isaacus.com/api-reference/errors#500-internal-server-error title: Internal server error status: 500 detail: An unexpected error occurred while processing the request. instance: null Chunking timeout error: summary: Chunking timeout error value: type: >- https://docs.isaacus.com/api-reference/errors#500-internal-server-error title: Chunking timeout error status: 500 detail: >- Chunking timed out. Did you try to chunk a very large text with a very low chunk size or very little variation in levels of whitespace? instance: null deprecated: false x-codeSamples: - lang: JavaScript source: |- import Isaacus from 'isaacus'; const client = new Isaacus({ apiKey: process.env['ISAACUS_API_KEY'], // This is the default and can be omitted }); const rerankingResponse = await client.rerankings.create({ model: 'kanon-2-reranker', query: 'What are the essential elements required to establish a negligence claim?', texts: [ 'To form a contract, there must be an offer, acceptance, consideration, and mutual intent to be bound.', 'Criminal cases involve a completely different standard, requiring proof beyond a reasonable doubt.', 'In a negligence claim, the plaintiff must prove duty, breach, causation, and damages.', 'Negligence in tort law requires establishing a duty of care that the defendant owed to the plaintiff.', 'The concept of negligence is central to tort law, with courts assessing whether a breach of duty caused harm.', ], }); console.log(rerankingResponse.results); - lang: Python source: |- import os from isaacus import Isaacus client = Isaacus( api_key=os.environ.get("ISAACUS_API_KEY"), # This is the default and can be omitted ) reranking_response = client.rerankings.create( model="kanon-2-reranker", query="What are the essential elements required to establish a negligence claim?", texts=["To form a contract, there must be an offer, acceptance, consideration, and mutual intent to be bound.", "Criminal cases involve a completely different standard, requiring proof beyond a reasonable doubt.", "In a negligence claim, the plaintiff must prove duty, breach, causation, and damages.", "Negligence in tort law requires establishing a duty of care that the defendant owed to the plaintiff.", "The concept of negligence is central to tort law, with courts assessing whether a breach of duty caused harm."], ) print(reranking_response.results) components: schemas: RerankingRequest: properties: model: oneOf: - type: string const: kanon-2-reranker - type: string const: kanon-universal-classifier description: >- The ID of the model to use for reranking, being either a [reranking model](https://docs.isaacus.com/models/introduction#reranking) or [universal classification model](https://docs.isaacus.com/models/introduction#universal-classification). examples: - kanon-2-reranker query: type: string maxLength: 10000000 minLength: 1 pattern: \S description: >- The query to evaluate the relevance of the texts to. The query must contain at least one non-whitespace character. Unlike the texts being reranked, the query cannot be so long that it exceeds the maximum input length of the reranker. examples: - >- What are the essential elements required to establish a negligence claim? texts: items: type: string type: array description: |- The texts to rerank. There must be at least one text. Each text must contain at least one non-whitespace character. examples: - - >- To form a contract, there must be an offer, acceptance, consideration, and mutual intent to be bound. - >- Criminal cases involve a completely different standard, requiring proof beyond a reasonable doubt. - >- In a negligence claim, the plaintiff must prove duty, breach, causation, and damages. - >- Negligence in tort law requires establishing a duty of care that the defendant owed to the plaintiff. - >- The concept of negligence is central to tort law, with courts assessing whether a breach of duty caused harm. top_n: oneOf: - type: integer minimum: 1 title: Positive integer description: A whole number greater than or equal to 1. examples: - 1 - type: 'null' description: |- The number of highest scoring results to return. If `null`, which is the default, all results will be returned. examples: - null is_iql: type: boolean description: >- Whether the query should be interpreted as an [Isaacus Query Language (IQL)](https://docs.isaacus.com/iql) query, which is not the case by default. If you allow untrusted users to construct their own queries, think carefully before enabling IQL since queries can be crafted to consume an excessively large amount of tokens. default: false examples: - false scoring_method: type: string enum: - auto - chunk_max - chunk_avg - chunk_min description: >- The method to use for producing an overall relevance score for a text that exceeds the model's local context window and has, therefore, been split into multiple chunks. `auto` is the default scoring method and is recommended for most use cases. Currently, it is equivalent to `chunk_max`. In the future, it will automatically select the best method based on the model and inputs. `chunk_max` uses the highest relevance score of all of a text's chunks. `chunk_avg` averages the relevance scores of all of a text's chunks. `chunk_min` uses the lowest relevance score of all of a text's chunks. default: auto examples: - auto chunking_options: oneOf: - $ref: '#/components/schemas/ChunkingOptions' - type: 'null' description: >- Settings for how texts should be chunked into smaller segments by [semchunk](https://github.com/isaacus-dev/semchunk) before reranking. If `null`, the texts will not be chunked and will instead be truncated to the maximum input length of the reranker less overhead if found to exceed that limit. Chunking is enabled by default. examples: - size: null overlap_ratio: null overlap_tokens: null type: object required: - model - query - texts title: Reranking request description: >- A request to rerank documents by their relevance to a query with an Isaacus reranker. examples: - model: kanon-2-reranker query: >- What are the essential elements required to establish a negligence claim? texts: - >- To form a contract, there must be an offer, acceptance, consideration, and mutual intent to be bound. - >- Criminal cases involve a completely different standard, requiring proof beyond a reasonable doubt. - >- In a negligence claim, the plaintiff must prove duty, breach, causation, and damages. - >- Negligence in tort law requires establishing a duty of care that the defendant owed to the plaintiff. - >- The concept of negligence is central to tort law, with courts assessing whether a breach of duty caused harm. top_n: null is_iql: false scoring_method: auto chunking_options: size: null overlap_ratio: null overlap_tokens: null RerankingResponse: properties: results: items: $ref: '#/components/schemas/RerankingResult' type: array description: >- The texts reranked by relevance to the query, in order from highest to lowest relevance score. examples: - - index: 2 score: 0.7727372261985272 - index: 3 score: 0.7332913519466231 - index: 4 score: 0.32399687407609323 - index: 1 score: 0.09480246485705024 - index: 0 score: 0.06929198572432578 usage: $ref: '#/components/schemas/RerankingUsage' type: object required: - results - usage title: Reranking response examples: - results: - index: 2 score: 0.7727372261985272 - index: 3 score: 0.7332913519466231 - index: 4 score: 0.32399687407609323 - index: 1 score: 0.09480246485705024 - index: 0 score: 0.06929198572432578 usage: input_tokens: 170 ValidationError: properties: type: type: string minLength: 1 title: Non-empty string description: A URI reference that identifies the problem type. default: https://docs.isaacus.com/api-reference/errors#400-validation-error examples: - https://docs.isaacus.com/api-reference/errors#400-validation-error title: type: string minLength: 1 title: Non-empty string description: A short, human-readable summary of the problem type. default: Validation error examples: - Validation error status: type: integer const: 400 description: >- The HTTP status code generated by the origin server for this occurrence of the problem. default: 400 examples: - 400 detail: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. default: The request was invalid or could not be processed. examples: - A string. - type: 'null' description: >- An optional human-readable explanation specific to this occurrence of the problem. default: The request was invalid or could not be processed. examples: - The request was invalid or could not be processed. instance: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. examples: - A string. - type: 'null' description: >- An optional URI reference that identifies the specific occurrence of the problem. examples: - null type: object required: [] title: Validation error description: An RFC 7807 problem detail object. examples: - type: https://docs.isaacus.com/api-reference/errors#400-validation-error title: Validation error status: 400 detail: The request was invalid or could not be processed. instance: null UnauthorizedAPIKeyError: properties: type: type: string minLength: 1 title: Non-empty string description: A URI reference that identifies the problem type. default: https://docs.isaacus.com/api-reference/errors#401-not-authenticated examples: - >- https://docs.isaacus.com/api-reference/errors#401-not-authenticated title: type: string minLength: 1 title: Non-empty string description: A short, human-readable summary of the problem type. default: Unauthorized API key error examples: - Unauthorized API key error status: type: integer const: 401 description: >- The HTTP status code generated by the origin server for this occurrence of the problem. default: 401 examples: - 401 detail: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. default: >- The API key you provided does not exist, is expired or revoked, or is not authorized to access this resource. examples: - A string. - type: 'null' description: >- An optional human-readable explanation specific to this occurrence of the problem. default: >- The API key you provided does not exist, is expired or revoked, or is not authorized to access this resource. examples: - >- The API key you provided does not exist, is expired or revoked, or is not authorized to access this resource. instance: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. examples: - A string. - type: 'null' description: >- An optional URI reference that identifies the specific occurrence of the problem. examples: - null type: object required: [] title: Unauthorized API key error description: An RFC 7807 problem detail object. examples: - type: https://docs.isaacus.com/api-reference/errors#401-not-authenticated title: Unauthorized API key error status: 401 detail: >- The API key you provided does not exist, is expired or revoked, or is not authorized to access this resource. instance: null AccountOverdueError: properties: type: type: string minLength: 1 title: Non-empty string description: A URI reference that identifies the problem type. default: https://docs.isaacus.com/api-reference/errors#402-payment-required examples: - https://docs.isaacus.com/api-reference/errors#402-payment-required title: type: string minLength: 1 title: Non-empty string description: A short, human-readable summary of the problem type. default: Account overdue error examples: - Account overdue error status: type: integer const: 402 description: >- The HTTP status code generated by the origin server for this occurrence of the problem. default: 402 examples: - 402 detail: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. default: >- Your account is overdue, please pay any outstanding invoices to continue using our services. examples: - A string. - type: 'null' description: >- An optional human-readable explanation specific to this occurrence of the problem. default: >- Your account is overdue, please pay any outstanding invoices to continue using our services. examples: - >- Your account is overdue, please pay any outstanding invoices to continue using our services. instance: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. examples: - A string. - type: 'null' description: >- An optional URI reference that identifies the specific occurrence of the problem. examples: - null type: object required: [] title: Account overdue error description: An RFC 7807 problem detail object. examples: - type: https://docs.isaacus.com/api-reference/errors#402-payment-required title: Account overdue error status: 402 detail: >- Your account is overdue, please pay any outstanding invoices to continue using our services. instance: null AccessForbiddenError: properties: type: type: string minLength: 1 title: Non-empty string description: A URI reference that identifies the problem type. default: https://docs.isaacus.com/api-reference/errors#403-access-forbidden examples: - https://docs.isaacus.com/api-reference/errors#403-access-forbidden title: type: string minLength: 1 title: Non-empty string description: A short, human-readable summary of the problem type. default: Access forbidden error examples: - Access forbidden error status: type: integer const: 403 description: >- The HTTP status code generated by the origin server for this occurrence of the problem. default: 403 examples: - 403 detail: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. default: You are not allowed to access this resource. examples: - A string. - type: 'null' description: >- An optional human-readable explanation specific to this occurrence of the problem. default: You are not allowed to access this resource. examples: - You are not allowed to access this resource. instance: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. examples: - A string. - type: 'null' description: >- An optional URI reference that identifies the specific occurrence of the problem. examples: - null type: object required: [] title: Access forbidden error description: An RFC 7807 problem detail object. examples: - type: https://docs.isaacus.com/api-reference/errors#403-access-forbidden title: Access forbidden error status: 403 detail: You are not allowed to access this resource. instance: null RequestTooLargeError: properties: type: type: string minLength: 1 title: Non-empty string description: A URI reference that identifies the problem type. default: https://docs.isaacus.com/api-reference/errors#413-request-too-large examples: - >- https://docs.isaacus.com/api-reference/errors#413-request-too-large title: type: string minLength: 1 title: Non-empty string description: A short, human-readable summary of the problem type. default: Request too large error examples: - Request too large error status: type: integer const: 413 description: >- The HTTP status code generated by the origin server for this occurrence of the problem. default: 413 examples: - 413 detail: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. default: >- The request is larger than the server is willing or able to process. examples: - A string. - type: 'null' description: >- An optional human-readable explanation specific to this occurrence of the problem. default: The request is larger than the server is willing or able to process. examples: - >- The request is larger than the server is willing or able to process. instance: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. examples: - A string. - type: 'null' description: >- An optional URI reference that identifies the specific occurrence of the problem. examples: - null type: object required: [] title: Request too large error description: An RFC 7807 problem detail object. examples: - type: https://docs.isaacus.com/api-reference/errors#413-request-too-large title: Request too large error status: 413 detail: The request is larger than the server is willing or able to process. instance: null InternalServerError: properties: type: type: string minLength: 1 title: Non-empty string description: A URI reference that identifies the problem type. default: >- https://docs.isaacus.com/api-reference/errors#500-internal-server-error examples: - >- https://docs.isaacus.com/api-reference/errors#500-internal-server-error title: type: string minLength: 1 title: Non-empty string description: A short, human-readable summary of the problem type. default: Internal server error examples: - Internal server error status: type: integer const: 500 description: >- The HTTP status code generated by the origin server for this occurrence of the problem. default: 500 examples: - 500 detail: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. default: An unexpected error occurred while processing the request. examples: - A string. - type: 'null' description: >- An optional human-readable explanation specific to this occurrence of the problem. default: An unexpected error occurred while processing the request. examples: - An unexpected error occurred while processing the request. instance: oneOf: - type: string minLength: 1 title: Non-empty string description: A string with at least one character. examples: - A string. - type: 'null' description: >- An optional URI reference that identifies the specific occurrence of the problem. examples: - null type: object required: [] title: Internal server error description: An RFC 7807 problem detail object. examples: - type: >- https://docs.isaacus.com/api-reference/errors#500-internal-server-error title: Internal server error status: 500 detail: An unexpected error occurred while processing the request. instance: null ChunkingOptions: properties: size: oneOf: - type: integer minimum: 1 title: Positive integer description: A whole number greater than or equal to 1. examples: - 1 - type: 'null' description: >- The maximum number of tokens allowed in a chunk. If `null`, the maximum input length of the model will be used less overhead. examples: - 512 overlap_ratio: oneOf: - type: number exclusiveMaximum: 1 minimum: 0 title: Unit interval (closed, open) description: A number greater than or equal to 0 and less than 1. examples: - 0.5 - type: 'null' description: |- The proportion of the chunk size by which chunks should overlap. The ratio must be less than 1. If `null`, no overlapping will occur unless `overlap_tokens` is set. `overlap_ratio` and `overlap_tokens` cannot both be set. examples: - 0.1 - null overlap_tokens: oneOf: - type: integer minimum: 0 title: Non-negative integer description: A whole number greater than or equal to 0. examples: - 0 - type: 'null' description: |- The number of tokens by which chunks should overlap. If `null`, no overlapping will occur unless `overlap_ratio` is set. `overlap_tokens` and `overlap_ratio` cannot both be set. examples: - null - 10 type: object required: [] title: Chunking options description: Options for how to split text into smaller chunks. examples: - size: 512 overlap_ratio: 0.1 - size: 512 overlap_tokens: 10 - size: 512 RerankingResult: properties: index: type: integer minimum: 0 title: Non-negative integer description: >- The index of the text in the input array of texts, starting from `0` (and, therefore, ending at the number of texts minus `1`). examples: - 2 score: type: number maximum: 1 minimum: 0 title: Unit interval description: >- A score between `0` and `1`, inclusive, representing the relevance of the text to the query. examples: - 0.7727372261985272 type: object required: - index - score title: Reranking result examples: - index: 2 score: 0.7727372261985272 RerankingUsage: properties: input_tokens: type: integer minimum: 1 title: Positive integer description: The number of tokens inputted to the model. examples: - 170 type: object required: - input_tokens title: Reranking usage description: >- Statistics about the usage of resources in the process of reranking the texts. examples: - input_tokens: 170 securitySchemes: APIKeyBearerTokenAuth: type: http description: >- An Isaacus-issued API key passed as a bearer token via the `Authorization` header in the format `Authorization: Bearer YOUR_API_KEY`. scheme: bearer bearerFormat: iuak_v1_APIKEYSECRET_CHECKSUM ````