openapi: 3.1.0
info:
  title: NeMo Retriever Text Reranking NIM
  description: A service for ranking passages by their relation to a query.
  version: 1.0.0
paths:
  /health:
    get:
      tags:
      - health
      summary: Health check
      description: Check the health status of the service.
      operationId: read_health
      responses:
        '200':
          description: The health status of the service.
          content:
            application/json:
              schema:
                type: object
                title: Response Read Health
  /v1/health/live:
    get:
      tags:
      - health
      summary: Service liveness check
      description: Check the liveness status of the service.
      operationId: read_health_live
      responses:
        '200':
          description: The service is live.
          content:
            application/json:
              schema: {}
        '503':
          description: The service is not live.
  /v1/health/ready:
    get:
      tags:
      - health
      summary: Service readiness check
      description: Check the readiness status of the service.
      operationId: read_health_ready
      responses:
        '200':
          description: The service is ready to accept inference requests.
          content:
            application/json:
              schema: {}
        '503':
          description: The service is not ready to accept inference requests.
  /v1/models:
    get:
      tags:
      - models
      summary: Returns the available models in the service
      description: Check the models available in the service.
      operationId: read_models
      responses:
        '200':
          description: The available models loaded in the service.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsResponse'
  /v1/ranking:
    post:
      tags:
      - ranking
      summary: Rank passages by their relation to a query.
      description: 'Order a list of passages by their relation to a query.


        Note that if a given query + passage pair is longer than the ranking model''s
        context window,

        it will be automatically truncated.'
      operationId: rank
      parameters:
      - name: content-type
        in: header
        required: true
        schema:
          type: string
          maxLength: 32
          pattern: .*
          title: Content-Type
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RankRequest'
      responses:
        '200':
          description: The ranked list of texts.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RankResponse'
        '422':
          description: The request was invalid.
components:
  schemas:
    ModelCard:
      properties:
        id:
          type: string
          maxLength: 1024
          pattern: .*
          title: Id
          examples:
          - NV-Rerank-QA
      type: object
      required:
      - id
      title: ModelCard
      description: A response from the models endpoint.
    ModelsResponse:
      properties:
        object:
          type: string
          maxLength: 4
          pattern: list
          title: Object
          default: list
        data:
          items:
            $ref: '#/components/schemas/ModelCard'
          type: array
          maxItems: 10
          title: Data
          examples:
          - id: NV-Rerank-QA
      type: object
      required:
      - data
      title: ModelsResponse
    MultiModalData:
      properties:
        text:
          type: string
          maxLength: 14598366
          minLength: 1
          pattern: .*
          title: Text
      additionalProperties: false
      type: object
      required:
      - text
      title: MultiModalData
      description: A type signifier for multimodal data.
    Rank:
      properties:
        index:
          type: integer
          maximum: 512.0
          minimum: 0.0
          format: int32
          title: Index
        logit:
          type: number
          title: Logit
      type: object
      required:
      - index
      - logit
      title: Rank
      description: A single ranked text.
    RankRequest:
      properties:
        model:
          type: string
          maxLength: 128
          minLength: 1
          pattern: .*
          title: Model
          examples:
          - nv-rerank-qa-mistral-4b:1
        query:
          allOf:
          - $ref: '#/components/schemas/MultiModalData'
          examples:
          - text: which way should i go?
        passages:
          items:
            $ref: '#/components/schemas/MultiModalData'
          type: array
          maxItems: 512
          minItems: 1
          title: Passages
          examples:
          - - text: two roads diverged in a yellow wood, and sorry i could not travel
                both and be one traveler, long i stood and looked down one as far
                as i could to where it bent in the undergrowth;
            - text: 'i shall be telling this with a sigh somewhere ages and ages hense:
                two roads diverged in a wood, and i, i took the one less traveled
                by, and that has made all the difference.'
        truncate:
          type: string
          enum:
          - END
          - NONE
          title: Truncate
          default: NONE
      type: object
      required:
      - model
      - query
      - passages
      title: RankRequest
      description: A request to the rank endpoint.
    RankResponse:
      properties:
        rankings:
          items:
            $ref: '#/components/schemas/Rank'
          type: array
          maxItems: 512
          minItems: 1
          title: Rankings
          examples:
          - - index: 1
              logit: 23.0
            - index: 0
              logit: -23.0
      type: object
      required:
      - rankings
      title: RankResponse
      description: A response from the ranking endpoint.
tags:
- name: health
  description: Check the health of the service.
- name: ranking
  description: Rank passages by their relation to a query.
