openapi: 3.1.0
info:
  title: NeMo Retriever Embedding NIM
  description: A service for embedding text and images.
  version: 1.9.0
paths:
  /v1/embeddings:
    post:
      summary: Create embeddings from the provided batches
      operationId: get_embeddings_v1_embeddings_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: 32
          pattern: .*
          default: application/json
          title: Content-Type
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EmbeddingRequest'
      responses:
        '200':
          description: Embeddings successfully returned
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EmbeddingResponse'
        '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/triton-inference-statistics:
    get:
      summary: Get Inference Statistics
      description: Get the inference statistics for the model.
      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/health/live:
    get:
      summary: Health Live
      operationId: health_live_v1_health_live_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
  /v1/health/ready:
    get:
      summary: Health Ready
      operationId: health_ready_v1_health_ready_get
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
  /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/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
    Embedding:
      properties:
        index:
          type: integer
          maximum: 8191.0
          minimum: 0.0
          format: int32
          title: Index
        embedding:
          anyOf:
          - items:
              anyOf:
              - type: number
              - type: integer
            type: array
            maxItems: 1048576
            minItems: 1
          - type: string
            maxLength: 8388608
            minLength: 1
            format: binary
          title: Embedding
        object:
          type: string
          maxLength: 9
          pattern: embedding
          title: Object
          default: embedding
      type: object
      required:
      - index
      - embedding
      title: Embedding
    EmbeddingRequest:
      properties:
        input:
          anyOf:
          - type: string
            maxLength: 16777216
            minLength: 1
            pattern: .*
          - items:
              type: string
              maxLength: 16777216
              minLength: 1
              pattern: .*
            type: array
            maxItems: 8191
            minItems: 0
          title: Input
          examples:
          - This is some text to be embedded.
        model:
          type: string
          maxLength: 512
          minLength: 1
          pattern: .*
          title: Model
          examples:
          - nvidia/llama-3.2-nv-embedqa-1b-v2
        input_type:
          anyOf:
          - $ref: '#/components/schemas/InputTypeValue'
          - type: 'null'
        encoding_format:
          type: string
          enum:
          - float
          - base64
          title: Encoding Format
          default: float
        embedding_type:
          $ref: '#/components/schemas/EmbeddingTypeValue'
          default: float
        dimensions:
          anyOf:
          - type: integer
            exclusiveMinimum: 2.0
          - type: 'null'
          title: Dimensions
          examples:
          - null
        modality:
          anyOf:
          - $ref: '#/components/schemas/ModalityValue'
            maxLength: 16777216
            minLength: 1
          - items:
              $ref: '#/components/schemas/ModalityValue'
              maxLength: 16777216
              minLength: 1
            type: array
            maxItems: 8191
            minItems: 0
          - type: 'null'
          title: Modality
          examples:
          - text
          - image
          - text_image
        user:
          anyOf:
          - type: string
            maxLength: 512
            minLength: 1
            pattern: .*
          - type: 'null'
          title: User
          examples:
          - user-identifier
        truncate:
          $ref: '#/components/schemas/TruncateValue'
          default: NONE
      additionalProperties: false
      type: object
      required:
      - input
      - model
      title: EmbeddingRequest
    EmbeddingResponse:
      properties:
        object:
          type: string
          maxLength: 4
          pattern: list
          title: Object
          default: list
        data:
          items:
            $ref: '#/components/schemas/Embedding'
          type: array
          maxItems: 8192
          minItems: 1
          title: Data
        model:
          type: string
          maxLength: 512
          minLength: 1
          pattern: .*
          title: Model
          examples:
          - nvidia/llama-3.2-nv-embedqa-1b-v2
        usage:
          $ref: '#/components/schemas/UsageInfo'
      type: object
      required:
      - data
      - model
      - usage
      title: EmbeddingResponse
    EmbeddingTypeValue:
      type: string
      enum:
      - float
      - binary
      - ubinary
      - int8
      - uint8
      title: EmbeddingTypeValue
    HealthResponse:
      properties:
        object:
          type: string
          title: Object
          default: health-response
        message:
          type: string
          title: Message
      type: object
      required:
      - message
      title: HealthResponse
    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
    InputTypeValue:
      type: string
      enum:
      - query
      - passage
      title: InputTypeValue
    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.
      type: object
      required:
      - assetInfo
      - licenseInfo
      - modelInfo
      - repository_override
      - version
      title: MetadataEndpointModel
      description: A model representing the metadata response.
    ModalityValue:
      type: string
      enum:
      - text
      - image
      - text_image
      title: ModalityValue
    ModelCard:
      properties:
        id:
          type: string
          maxLength: 1024
          minLength: 1
          pattern: .*
          title: Id
          examples:
          - nvidia/llama-3.2-nv-embedqa-1b-v2
        created:
          type: integer
          maximum: 4294967295.0
          minimum: 0.0
          title: Created
          default: 0
        object:
          type: string
          maxLength: 5
          pattern: model
          title: Object
          default: model
        owned_by:
          type: string
          maxLength: 1024
          pattern: .*
          title: Owned By
          default: organization-owner
      type: object
      required:
      - id
      title: ModelCard
    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
        last_inference:
          type: integer
          title: Last Inference
        inference_count:
          type: integer
          title: Inference Count
        execution_count:
          type: integer
          title: Execution Count
        inference_stats:
          $ref: '#/components/schemas/InferenceStatisticsDetail'
        response_stats:
          anyOf:
          - type: object
          - type: 'null'
          title: Response Stats
        memory_usage:
          anyOf:
          - items: {}
            type: array
          - type: 'null'
          title: Memory Usage
        batch_stats:
          items:
            $ref: '#/components/schemas/BatchStat'
          type: array
          title: Batch Stats
      type: object
      required:
      - name
      - version
      - last_inference
      - inference_count
      - execution_count
      - inference_stats
      - batch_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: 1023
          minItems: 0
          title: Data
      type: object
      required:
      - data
      title: ModelsResponse
    Statistic:
      properties:
        count:
          type: integer
          title: Count
          default: 0
        ns:
          type: integer
          title: Ns
          default: 0
      type: object
      title: Statistic
    TruncateValue:
      type: string
      enum:
      - START
      - END
      - NONE
      title: TruncateValue
    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
