> ## Documentation Index
> Fetch the complete documentation index at: https://developers.unbridaled.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Diamonds AI Search

> Perform AI search using predefined merchant diamond templates. Each merchant template has a `group` to allow results from different templates from being returned at once. For example, you can create a `group` called `ai_solitaire` with `Standard`, `Premium` and `Ideal` templates if you plan to display the result together.

A `group` in the merchant template can roughly map to a `collection` of products in Shopify or other e-commerce platforms. This allows you to reuse different predefined templates easily for a `group` of products. Refer to `List Merchant Templates` API to learn about Merchant diamonds templates or check our tutorial to learn more about our AI merchant template concept here: [AI Curated Results](https://docs.unbridaled.ai/settings/ai-curated-results).



## OpenAPI

````yaml post /api/v3/diamonds/get_diamonds_by_merchant_templates
openapi: 3.1.0
info:
  title: Unbridaled Marketplace Merchant API v3
  description: Developer API to integrate with Unbridaled Marketplace (v3)
  version: 3.0.0
servers:
  - url: https://api-staging.unbridaled.ai
    description: Sandbox API
  - description: Production API
    url: https://api.unbridaled.ai
security:
  - apikeyAuth: []
tags:
  - name: Diamonds
  - name: Inventory
  - name: Orders
  - name: Merchant Templates
  - name: Merchant Addresses
  - name: Profit Margins
  - name: Defaults
paths:
  /api/v3/diamonds/get_diamonds_by_merchant_templates:
    post:
      tags:
        - Diamonds
      summary: Diamonds AI Search
      description: >-
        Perform AI search using predefined merchant diamond templates. Each
        merchant template has a `group` to allow results from different
        templates from being returned at once. For example, you can create a
        `group` called `ai_solitaire` with `Standard`, `Premium` and `Ideal`
        templates if you plan to display the result together.


        A `group` in the merchant template can roughly map to a `collection` of
        products in Shopify or other e-commerce platforms. This allows you to
        reuse different predefined templates easily for a `group` of products.
        Refer to `List Merchant Templates` API to learn about Merchant diamonds
        templates or check our tutorial to learn more about our AI merchant
        template concept here: [AI Curated
        Results](https://docs.unbridaled.ai/settings/ai-curated-results).
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                weight:
                  type: number
                  description: Weight of the diamond.
                currency_code:
                  type: string
                  description: >-
                    ISO-3 currency code to return the prices in. Defaults to
                    USD.
                shape:
                  type: string
                  description: Shape to perform the AI search on.
                count_per_grade:
                  type: integer
                  minimum: 1
                  maximum: 2
                  description: >-
                    Determines if to return 1 result or 2 result per template.
                    Use 1 for single and 2 for pair.
                types:
                  type: array
                  items:
                    type: string
                    enum:
                      - mined
                      - lab grown
                ratio_min:
                  type: number
                ratio_max:
                  type: number
                merchant_template_filters:
                  type: object
                  properties:
                    group:
                      type: string
                      description: Group of the merchant templates to return.
                  required:
                    - group
              required:
                - weight
                - shape
                - types
            examples:
              DiamondsAISearchRequest:
                value:
                  shape: oval
                  types:
                    - mined
                    - lab grown
                  count_per_grade: 1
                  ratio_min: 1.35
                  ratio_max: 1.55
                  merchant_template_filters:
                    group: ai_solitaire
                  weight: '1.25'
        description: ''
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
                  properties:
                    base_currency_code:
                      type: string
                    base_retail_price:
                      type: integer
                    base_wholesale_price:
                      type: integer
                    can_hold:
                      type: boolean
                    cert_num:
                      type: string
                    cert_url:
                      type: string
                    clarity:
                      type: string
                    clarity_max:
                      type: 'null'
                    color:
                      type: string
                    color_max:
                      type: 'null'
                    country_code:
                      type: string
                    created_on:
                      type: string
                    crown_angle:
                      type:
                        - 'null'
                        - number
                    culet_size:
                      type:
                        - 'null'
                        - string
                    currency_code:
                      type: string
                    cut_code:
                      type: string
                    cut_grade:
                      type: 'null'
                    cut_grade_description:
                      type: 'null'
                    days_to_return:
                      type: integer
                    delivery_days_max:
                      type: integer
                    delivery_days_min:
                      type: integer
                    depth:
                      type: number
                    depth_percentage:
                      type: number
                    enabled:
                      type: boolean
                    exchange_rate:
                      type: integer
                    eye_clean:
                      type: string
                    fancy_color_intensity:
                      type: 'null'
                    fluorescence:
                      type: string
                    girdle_max:
                      type: string
                    girdle_min:
                      type: string
                    grow_method:
                      type:
                        - 'null'
                        - string
                    hold_merchant_uuid:
                      type: 'null'
                    id:
                      type: integer
                    image_bottom_url:
                      type: 'null'
                    image_top_url:
                      type: string
                    is_fancy:
                      type: boolean
                    is_manual:
                      type: boolean
                    is_pair:
                      type: boolean
                    is_sustainable:
                      type: boolean
                    lab:
                      type: string
                    length:
                      type: number
                    media_requested:
                      type: boolean
                    memo:
                      type: boolean
                    memo_days_to_return:
                      type: integer
                    merchant_template_group:
                      type: string
                    merchant_template_label:
                      type: string
                      description: >-
                        The label of the merchant template the diamond was
                        classified under. For example, if the label of the
                        merchant template is "ideal", then the `label` will
                        return "ideal" in the response.
                    merchant_template_position:
                      type: integer
                    merchant_template_uuid:
                      type: string
                    off_rap_percentage:
                      type: 'null'
                    on_hold:
                      type: boolean
                    original_imported_ext_url:
                      type: string
                    overtone:
                      type: 'null'
                    parcel:
                      type: boolean
                    pavilion_angle:
                      type:
                        - 'null'
                        - number
                    pavilion_depth:
                      type:
                        - 'null'
                        - number
                    pcs:
                      type: integer
                    polish_grade:
                      type: string
                    product_type:
                      type: string
                    quality:
                      type: 'null'
                    quantity:
                      type: integer
                    ratio:
                      type: number
                    ratio_group:
                      type: string
                    retail_price:
                      type: integer
                    returnable:
                      type:
                        - boolean
                        - 'null'
                    shade:
                      type: 'null'
                    shape:
                      type: string
                    shape_icon_url:
                      type: string
                    shape_icon_url_png:
                      type: string
                    shape_image_url:
                      type: string
                    sku:
                      type: string
                    stone_type:
                      type: 'null'
                    sustainability_details:
                      type: 'null'
                    symmetry_grade:
                      type: string
                    table_percentage:
                      type: integer
                    type:
                      type: string
                    updated_on:
                      type: string
                    ux_url:
                      type: string
                    v360_info:
                      type: 'null'
                    v360_json_base_url:
                      type: string
                    video_url:
                      type: string
                    weight:
                      type: number
                    wholesale_price:
                      type: integer
                    width:
                      type:
                        - number
              examples:
                DiamondsAISearchResponse:
                  value:
                    - base_currency_code: USD
                      base_retail_price: 490
                      base_wholesale_price: 430
                      can_hold: true
                      cert_num: '524226131'
                      cert_url: https://api.igi.org/viewpdf.php?r=524226131
                      clarity: VS1
                      clarity_max: null
                      color: F
                      color_max: null
                      country_code: USA
                      created_on: '2023-12-04 15:34:45.897194'
                      crown_angle: 37.5
                      culet_size: 'N'
                      currency_code: USD
                      cut_code: brilliant_cut
                      cut_grade: null
                      cut_grade_description: null
                      days_to_return: 0
                      delivery_days_max: 2
                      delivery_days_min: 1
                      depth: 3.84
                      depth_percentage: 62.1
                      enabled: true
                      exchange_rate: 1
                      eye_clean: 'yes'
                      fancy_color_intensity: null
                      fluorescence: None
                      girdle_max: MD
                      girdle_min: TN
                      grow_method: cvd
                      hold_merchant_uuid: null
                      id: 909651
                      image_bottom_url: null
                      image_top_url: ''
                      is_fancy: false
                      is_manual: false
                      is_pair: false
                      is_sustainable: false
                      lab: IGI
                      length: 8.68
                      media_requested: false
                      memo: true
                      memo_days_to_return: 5
                      merchant_template_group: ai_solitaire
                      merchant_template_label: IDEAL
                      merchant_template_position: 1
                      merchant_template_uuid: 2d978b0f-8541-4825-8e34-353fea78bb84
                      off_rap_percentage: null
                      on_hold: false
                      original_imported_ext_url: https://hd360video.com/video/Get?q=BMLGD-93456
                      overtone: null
                      parcel: false
                      pavilion_angle: 40.3
                      pavilion_depth: 43.5
                      pcs: 1
                      polish_grade: EX
                      product_type: diamond
                      quality: null
                      quantity: 1
                      ratio: 1.4
                      ratio_group: rectangular
                      retail_price: 490
                      returnable: null
                      shade: null
                      shape: oval
                      shape_icon_url: >-
                        https://unbridaled-dev.s3.amazonaws.com/das/static/images/shape_icons/shape-oval.svg
                      shape_icon_url_png: >-
                        https://unbridaled-dev.s3.amazonaws.com/das/static/images/shape_icons/shape-oval.png
                      shape_image_url: >-
                        https://unbridaled-dev.s3.amazonaws.com/das/static/images/shape_images/brilliant-oval.png
                      sku: UB62945EDB2B
                      stone_type: null
                      sustainability_details: null
                      symmetry_grade: EX
                      table_percentage: 60
                      type: lab grown
                      updated_on: '2024-02-18 10:55:52.577049'
                      ux_url: >-
                        https://unbridaled-dev.s3.amazonaws.com/das/v360/ub/v1/player/video/player.html?d=UB62945EDB2B
                      v360_info: null
                      v360_json_base_url: >-
                        https://unbridaled-dev.s3.amazonaws.com/das/uploads/v360/imaged/UB62945EDB2B
                      video_url: ''
                      weight: 1.29
                      wholesale_price: 430
                      width: 6.18
components:
  securitySchemes:
    apikeyAuth:
      type: http
      scheme: bearer

````