Orq.ai Rerank API

openapi: 3.2.0
info:
  title: orq.ai Rerank API
  version: '2.0'
  description: orq.ai API documentation
servers:
- url: https://my.orq.ai
security:
- ApiKey: []
tags:
- name: Rerank
paths:
  /v2/router/rerank:
    post:
      operationId: createRerank
      summary: Create rerank
      tags:
      - Rerank
      x-speakeasy-group: router.rerank
      x-speakeasy-name-override: create
      x-cli-group: rerank
      x-cli-name: create
      x-speakeasy-ignore: false
      x-orq-gateway-group: 'true'
      description: Rerank a list of documents based on their relevance to a query.
      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: integer
                  minimum: 1
                  description: The number of most relevant documents or indices to return, defaults to the length of the documents
                return_documents:
                  type: boolean
                  description: Whether to return the documents in the response
                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
                      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: 3600
                      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-5.6-sol
                            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.
                plugins:
                  type: array
                  items:
                    $ref: '#/components/schemas/PIIRedactionPlugin'
                  description: Request-scoped transforms applied to the text exchanged with the model. Currently supports `pii_redaction`, which replaces PII with placeholders before the provider sees it and restores the original values in the response.
                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-5.4-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: 3600
                          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
                          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-5.6-sol
                                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.
                      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.
                    fallback_on_codes:
                      type: array
                      items:
                        type: integer
                        minimum: 400
                        maximum: 599
                      maxItems: 20
                      description: HTTP status codes that trigger fallback. Enter up to 20 unique integers from 400 to 599. When omitted or empty, defaults to [408, 429, 500, 502, 503, 504, 529].
                fallback_on_codes:
                  type: array
                  items:
                    type: integer
                    minimum: 400
                    maximum: 599
                  maxItems: 20
                  description: HTTP status codes that trigger fallback. Enter up to 20 unique integers from 400 to 599. When omitted or empty, defaults to [408, 429, 500, 502, 503, 504, 529].
              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
        '401':
          description: Authentication required. See https://docs.orq.ai/reference/errors for the error codes.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIErrorResponse'
components:
  schemas:
    APIErrorResponse:
      type: object
      additionalProperties: false
      properties:
        error:
          $ref: '#/components/schemas/APIError'
      required:
      - error
    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
    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.
    APIError:
      additionalProperties: false
      properties:
        code:
          type:
          - string
          - 'null'
        failures: {}
        message:
          type: string
        param:
          type:
          - string
          - 'null'
        type:
          type: string
      required:
      - message
      - type
      - param
      - code
      type: object
    PIIRedactionPlugin:
      type: object
      properties:
        id:
          type: string
          enum:
          - pii_redaction
          description: PII redaction plugin.
        language:
          type: string
          description: Detector language. Accepts "auto" to detect the language per request; GET /v2/pii/capabilities lists the concrete languages and does not include "auto". Omitting the field defaults to "auto".
        regions:
          type: array
          items:
            type: string
          description: 'Region codes selecting whole regions of coverage (e.g. "nl", "gb"). Every entity type those regions cover is redacted, alongside the base catalog. ["all"] is exclusive, and leaving both this and entities empty also runs every region, so selecting nothing is the widest request rather than the narrowest. Combines with entities: the two selections are unioned, so entities adds types on top of the region coverage.'
        entities:
          type: array
          items:
            type: string
          description: The entity types to redact. A named type is redacted even when it belongs to a region, so a region's types can be selected individually without naming the region. On its own this is a strict allowlist; alongside regions it adds to the region coverage. See GET /v2/pii/capabilities for valid types.
        entity_thresholds:
          type: object
          additionalProperties:
            type: number
            minimum: 0
            maximum: 1
          description: Per-entity confidence cutoff overrides in [0,1]. Tunes confidence only and never changes which types are redacted, so every key must also appear in entities.
        threshold:
          type: number
          minimum: 0
          maximum: 1
          description: Baseline confidence cutoff applied to every entity type without a per-entity override.
        on_failure:
          type: string
          enum:
          - block
          - passthrough
          description: Behaviour when detection fails.
      required:
      - id
      additionalProperties: false
      title: PII redaction plugin
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: JWT
externalDocs:
  url: https://docs.orq.ai
  description: orq.ai Documentation
x-speakeasy-timeout: 600000