> ## Documentation Index > Fetch the complete documentation index at: https://docs.orq.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create rerank > Rerank a list of documents based on their relevance to a query. ## OpenAPI ````yaml post /v2/router/rerank openapi: 3.1.0 info: title: orq.ai API version: '2.0' description: orq.ai API documentation servers: - url: https://api.orq.ai security: - ApiKey: [] tags: - name: Guardrail Rules - name: Policies - name: Routing Rules - name: Files description: File upload and retrieval operations. - name: FilesService - name: Projects description: Projects organize resources within a workspace - name: ProjectsService - name: Skills description: >- Skills are modular instructions you can use to codify processes and conventions - name: SkillsService - name: Responses - description: >- Run agents on a cadence — cron, interval, or one-off. Minimum firing interval is 1 hour. name: Agent Schedules - name: Reporting description: >- GenAI reporting API over canonical analytics rollups. Accepts a metric name, time range, grain, group-by, and filters; returns a typed time series and optional totals. - name: ReportingService description: |- ReportingService exposes a single QueryReport RPC that maps allowlisted analytics payloads onto safe rollup queries. Callers never send SQL; the backend picks the rollup family and grain from the metric catalogue, the requested range, and the requested grouping. externalDocs: url: https://docs.orq.ai description: orq.ai Documentation paths: /v2/router/rerank: post: tags: - Rerank summary: Create rerank description: Rerank a list of documents based on their relevance to a query. operationId: createRerank requestBody: required: true description: input content: application/json: schema: type: object properties: query: type: string description: The search query documents: type: array items: type: string description: >- A list of texts that will be compared to the `query`. For optimal performance we recommend against sending more than 1,000 documents in a single request. model: type: string description: The identifier of the model to use top_n: type: number description: >- The number of most relevant documents or indices to return, defaults to the length of the documents filename: type: - string - 'null' description: The filename of the document to rerank name: type: string description: >- The name to display on the trace. If not specified, the default system name will be used. fallbacks: type: array items: type: object properties: model: type: string description: Fallback model identifier required: - model description: Array of fallback models to use if primary model fails retry: type: object properties: count: type: number minimum: 1 maximum: 5 default: 3 description: Number of retry attempts (1-5) example: 3 on_codes: type: array items: type: number minimum: 100 maximum: 599 minItems: 1 default: - 429 description: HTTP status codes that trigger retry logic example: - 429 - 500 - 502 - 503 - 504 description: Retry configuration for the request cache: type: object properties: ttl: type: number minimum: 1 maximum: 259200 default: 1800 description: >- Time to live for cached responses in seconds. Maximum 259200 seconds (3 days). example: 3600 type: type: string enum: - exact_match required: - type description: Cache configuration for the request. load_balancer: oneOf: - type: object properties: type: type: string enum: - weight_based models: type: array items: type: object properties: model: type: string description: Model identifier for load balancing example: openai/gpt-4o weight: type: number minimum: 0.001 maximum: 1 default: 0.5 description: >- Weight assigned to this model for load balancing example: 0.7 required: - model required: - type - models description: Load balancer configuration for the request. timeout: type: object properties: call_timeout: type: number minimum: 1 description: Timeout value in milliseconds example: 30000 required: - call_timeout description: >- Timeout configuration to apply to the request. If the request exceeds the timeout, it will be retried or fallback to the next model if configured. orq: type: object properties: name: type: string description: >- The name to display on the trace. If not specified, the default system name will be used. fallbacks: type: array items: type: object properties: model: type: string description: Fallback model identifier example: openai/gpt-4o-mini required: - model description: Array of fallback models to use if primary model fails cache: type: object properties: ttl: type: number minimum: 1 maximum: 259200 default: 1800 description: >- Time to live for cached responses in seconds. Maximum 259200 seconds (3 days). example: 3600 type: type: string enum: - exact_match required: - type description: Cache configuration for the request. retry: type: object properties: count: type: number minimum: 1 maximum: 5 default: 3 description: Number of retry attempts (1-5) example: 3 on_codes: type: array items: type: number minimum: 100 maximum: 599 minItems: 1 default: - 429 description: HTTP status codes that trigger retry logic example: - 429 - 500 - 502 - 503 - 504 description: Retry configuration for the request identity: $ref: '#/components/schemas/PublicIdentity' contact: $ref: '#/components/schemas/PublicContact' load_balancer: oneOf: - type: object properties: type: type: string enum: - weight_based models: type: array items: type: object properties: model: type: string description: Model identifier for load balancing example: openai/gpt-4o weight: type: number minimum: 0.001 maximum: 1 default: 0.5 description: >- Weight assigned to this model for load balancing example: 0.7 required: - model required: - type - models description: Array of models with weights for load balancing requests example: type: weight_based models: - model: openai/gpt-4o weight: 0.7 - model: anthropic/claude-3-5-sonnet weight: 0.3 timeout: type: object properties: call_timeout: type: number minimum: 1 description: Timeout value in milliseconds example: 30000 required: - call_timeout description: >- Timeout configuration to apply to the request. If the request exceeds the timeout, it will be retried or fallback to the next model if configured. required: - query - documents - model responses: '200': description: Returns the reranked documents. content: application/json: schema: type: object properties: id: type: string description: A unique identifier for the rerank. object: type: string enum: - list results: type: array items: type: object properties: object: type: string enum: - rerank description: The object type, which is always `rerank`. index: type: number description: >- Corresponds to the index in the original list of documents to which the ranked document belongs. relevance_score: type: number description: >- Relevance scores are normalized to be in the range [0, 1]. Scores close to 1 indicate a high relevance to the query, and scores closer to 0 indicate low relevance. document: type: object properties: text: type: string description: The text of the document to rerank required: - text description: >- If return_documents is set as false this will return none, if true it will return the documents passed in required: - object - index - relevance_score description: An ordered list of ranked documents usage: type: object properties: total_tokens: type: number description: The total number of tokens used in the rerank required: - total_tokens required: - object - results components: schemas: PublicIdentity: type: object properties: id: type: string description: Unique identifier for the contact example: contact_01ARZ3NDEKTSV4RRFFQ69G5FAV display_name: type: string description: Display name of the contact example: Jane Doe email: type: string format: email description: Email address of the contact example: jane.doe@example.com metadata: type: array items: type: object additionalProperties: {} description: >- A hash of key/value pairs containing any other data about the contact example: - department: Engineering role: Senior Developer logo_url: type: string description: URL to the contact's avatar or logo example: https://example.com/avatars/jane-doe.jpg tags: type: array items: type: string description: A list of tags associated with the contact example: - hr - engineering required: - id description: >- Information about the identity making the request. If the identity does not exist, it will be created automatically. PublicContact: type: object properties: id: type: string description: Unique identifier for the contact example: contact_01ARZ3NDEKTSV4RRFFQ69G5FAV display_name: type: string description: Display name of the contact example: Jane Doe email: type: string format: email description: Email address of the contact example: jane.doe@example.com metadata: type: array items: type: object additionalProperties: {} description: >- A hash of key/value pairs containing any other data about the contact example: - department: Engineering role: Senior Developer logo_url: type: string description: URL to the contact's avatar or logo example: https://example.com/avatars/jane-doe.jpg tags: type: array items: type: string description: A list of tags associated with the contact example: - hr - engineering required: - id description: >- @deprecated Use identity instead. Information about the contact making the request. deprecated: true securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: JWT ````