openapi: 3.1.0
info:
  title: NeMo Retriever Reranking NIM
  description: A service for ranking passages by their relation to a query.
  version: 1.10.0
paths:
  /v1/triton-inference-statistics:
    get:
      summary: Get Inference Statistics
      description: Get the inference statistics for all models served by Triton.
      operationId: get_inference_statistics_v1_triton_inference_statistics_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelStatisticsResponse'
  /v1/models:
    get:
      summary: Get Models
      operationId: get_models_v1_models_get
      responses:
        '200':
          description: The available models loaded in the service.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelsResponse'
  /v1/ranking:
    post:
      summary: Rank passages by their relation to a query.
      operationId: rank_v1_ranking_post
      parameters:
      - name: nvcf-asset-dir
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Nvcf-Asset-Dir
      - name: content-type
        in: header
        required: false
        schema:
          type: string
          maxLength: 128
          pattern: .*
          default: application/json
          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'
        '400':
          description: Unable to validate the request due to client error
        '404':
          description: Unable to find the specified model
        '415':
          description: This endpoint expects application/json
        '422':
          description: The request was invalid
        '503':
          description: Model evaluator was unavailable, try again momentarily
  /v1/health/live:
    get:
      summary: Health Live
      operationId: health_live_v1_health_live_get
      responses:
        '200':
          description: Service is live
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NIMHealthSuccessResponse'
        '503':
          description: Service is not live
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NIMErrorResponse'
  /v1/health/ready:
    get:
      summary: Health Ready
      operationId: health_ready_v1_health_ready_get
      responses:
        '200':
          description: Service is ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NIMHealthSuccessResponse'
        '503':
          description: Service is not ready
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NIMErrorResponse'
  /v1/metrics:
    get:
      summary: Metrics
      description: Handler for metrics endpoint.
      operationId: metrics_v1_metrics_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: string
                title: Response Metrics V1 Metrics Get
  /v1/license:
    get:
      summary: License
      description: Handler for license endpoint.
      operationId: license_v1_license_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LicenseEndpointModel'
  /v1/metadata:
    get:
      summary: Metadata
      description: Handler for metadata endpoint.
      operationId: metadata_v1_metadata_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetadataEndpointModel'
  /v1/version:
    get:
      summary: Version
      description: Handler for version endpoint.
      operationId: version_v1_version_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NIMVersionResponse'
  /v1/manifest:
    get:
      summary: Manifest
      description: Handler for the manifest endpoint.
      operationId: manifest_v1_manifest_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ManifestEndpointModel'
components:
  schemas:
    BatchStat:
      properties:
        batch_size:
          type: integer
          title: Batch Size
        compute_input:
          $ref: '#/components/schemas/Statistic'
        compute_infer:
          $ref: '#/components/schemas/Statistic'
        compute_output:
          $ref: '#/components/schemas/Statistic'
      type: object
      required:
      - batch_size
      - compute_input
      - compute_infer
      - compute_output
      title: BatchStat
    InferenceStatisticsDetail:
      properties:
        success:
          $ref: '#/components/schemas/Statistic'
        fail:
          $ref: '#/components/schemas/Statistic'
        queue:
          $ref: '#/components/schemas/Statistic'
        compute_input:
          $ref: '#/components/schemas/Statistic'
        compute_infer:
          $ref: '#/components/schemas/Statistic'
        compute_output:
          $ref: '#/components/schemas/Statistic'
        cache_hit:
          $ref: '#/components/schemas/Statistic'
        cache_miss:
          $ref: '#/components/schemas/Statistic'
      type: object
      required:
      - success
      - fail
      - queue
      - compute_input
      - compute_infer
      - compute_output
      - cache_hit
      - cache_miss
      title: InferenceStatisticsDetail
    LicenseEndpointModel:
      properties:
        name:
          type: string
          title: Name
          description: The name of the license for the NIM container.
        path:
          type: string
          title: Path
          description: The filepath within the container containing the license content.
        sha:
          type: string
          title: Sha
          description: A SHA1 hash of the license contents.
        size:
          type: integer
          title: Size
          description: The number of characters in the license content.
        url:
          type: string
          title: Url
          description: The url where this license is hosted externally.
        type:
          type: string
          const: file
          title: Type
          description: The format of the license content.
        content:
          type: string
          title: Content
          description: The license text.
      type: object
      required:
      - name
      - path
      - sha
      - size
      - url
      - type
      - content
      title: LicenseEndpointModel
      description: A model representing the license response.
    ManifestEndpointModel:
      properties:
        manifest_file:
          type: string
          title: Manifest File
          description: The content of the manifest file describing the required model
            artifacts.
        repository_override:
          type: string
          title: Repository Override
          description: Alternate location used to retrieve artifacts from manifest
            file.
      type: object
      required:
      - manifest_file
      - repository_override
      title: ManifestEndpointModel
      description: A model representing the manifest response.
    MetadataEndpointModel:
      properties:
        assetInfo:
          items:
            type: string
          type: array
          title: Assetinfo
          description: A list of required container assets excluding model artifacts
        licenseInfo:
          $ref: '#/components/schemas/LicenseEndpointModel'
          description: The license info.
        modelInfo:
          items:
            $ref: '#/components/schemas/ModelInfo'
          type: array
          title: Modelinfo
          description: A list of models being served by the NIM.
        repository_override:
          type: string
          title: Repository Override
          description: Alternate location used to retrieve artifacts from manifest
            file.
        version:
          type: string
          title: Version
          description: The version of the NIM service.
        selectedModelProfileId:
          type: string
          title: Selectedmodelprofileid
          description: The ID of the currently selected model profile.
      type: object
      required:
      - assetInfo
      - licenseInfo
      - modelInfo
      - repository_override
      - version
      - selectedModelProfileId
      title: MetadataEndpointModel
      description: A model representing the metadata response.
    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.
    ModelInfo:
      properties:
        modelUrl:
          type: string
          title: Modelurl
        shortName:
          type: string
          title: Shortname
      type: object
      required:
      - modelUrl
      - shortName
      title: ModelInfo
      description: A model representing the model response.
    ModelStat:
      properties:
        name:
          type: string
          title: Name
        version:
          type: string
          title: Version
        inference_stats:
          $ref: '#/components/schemas/InferenceStatisticsDetail'
        inference_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Inference Count
        last_inference:
          anyOf:
          - type: integer
          - type: 'null'
          title: Last Inference
        execution_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Execution Count
        response_stats:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Response Stats
        memory_usage:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Memory Usage
        batch_stats:
          anyOf:
          - items:
              $ref: '#/components/schemas/BatchStat'
            type: array
          - type: 'null'
          title: Batch Stats
      type: object
      required:
      - name
      - version
      - inference_stats
      title: ModelStat
    ModelStatisticsResponse:
      properties:
        model_stats:
          items:
            $ref: '#/components/schemas/ModelStat'
          type: array
          title: Model Stats
      type: object
      required:
      - model_stats
      title: ModelStatisticsResponse
    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
        image:
          anyOf:
          - type: string
          - type: 'null'
          title: Image
          description: Image as base64 data URL (data:image/png;base64,...) or asset
            ID reference (data:image/png;asset_id,my_image.png). Only supported for
            VLM reranking models.
          examples:
          - data:image/png;base64,iVBORw0KGgo...
      additionalProperties: false
      type: object
      required:
      - text
      title: MultiModalData
      description: 'A type signifier for multimodal data.

        Supports text-only or text+image inputs for VLM reranking models.'
    NIMErrorResponse:
      properties:
        error:
          additionalProperties: true
          type: object
          title: Error
          description: Error details
      type: object
      required:
      - error
      title: NIMErrorResponse
      description: Error response model.
    NIMHealthSuccessResponse:
      properties:
        object:
          type: string
          title: Object
          description: The object of the health response.
          default: health.response
        message:
          type: string
          title: Message
          description: The message of the health response.
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
          description: The status of the health response for backwards compatibility.
      type: object
      required:
      - message
      title: NIMHealthSuccessResponse
      description: A model representing the health success response.
    NIMVersionResponse:
      properties:
        release:
          type: string
          title: Release
          description: The product release version of NIM for LLMs.
        api:
          type: string
          title: Api
          description: The server API version running inside the NIM.
      type: object
      required:
      - release
      - api
      title: NIMVersionResponse
      description: A model representing versions of the NIM
    QueryData:
      properties:
        text:
          type: string
          maxLength: 14598366
          minLength: 1
          pattern: .*
          title: Text
      additionalProperties: false
      type: object
      required:
      - text
      title: QueryData
      description: 'A type for query data. Queries are text-only (the VLM reranker''s
        cross-encoder

        format only has a doc_image slot — the query is always text).'
    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:
          - nvidia/llama-nemotron-rerank-vl-1b-v2
        query:
          $ref: '#/components/schemas/QueryData'
          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
      additionalProperties: false
      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
        usage:
          $ref: '#/components/schemas/UsageInfo'
      type: object
      required:
      - rankings
      - usage
      title: RankResponse
      description: A response from the ranking endpoint.
    Statistic:
      properties:
        count:
          type: integer
          title: Count
          default: 0
        ns:
          type: integer
          title: Ns
          default: 0
      type: object
      title: Statistic
    UsageInfo:
      properties:
        prompt_tokens:
          type: integer
          maximum: 4294967295.0
          minimum: 0.0
          title: Prompt Tokens
          default: 0
        total_tokens:
          type: integer
          maximum: 4294967295.0
          minimum: 0.0
          title: Total Tokens
          default: 0
      type: object
      title: UsageInfo
