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

# Search Public Merchant Products

> Search across all public merchants and products with optional merchant, pricing, stock, marketplace, and localization filters.



## OpenAPI

````yaml /openapi.json post /api/v1/search
openapi: 3.1.0
info:
  title: OmniCommerce API
  version: 1.0.0
  license:
    name: Proprietary
    url: https://omnicommerce.sg/terms
  description: >-
    OmniCommerce API surface for agents and developer integrations. Includes
    public endpoints (merchant discovery, product search, compare, catalog, ACO
    retrieval) and authenticated endpoints (product management via API key
    Bearer tokens).
servers:
  - url: https://omnicommerce.sg
    description: Production
  - url: http://localhost:3000
    description: Local development
security: []
tags:
  - name: agentic-checkout
    description: Merchant-fulfilled agentic checkout
    x-group: Agentic Checkout
  - name: commerce
    description: Root commerce discovery
    x-group: Commerce
  - name: developer-platform
    description: Authenticated developer platform APIs
    x-group: Developer Platform
  - name: looks
    description: AI-styled product looks
    x-group: Looks
  - name: oauth
    description: OAuth token endpoints
    x-group: OAuth
  - name: orders
    description: Workspace and agentic orders
    x-group: Orders
  - name: organizations
    description: Organization management
    x-group: Organizations
  - name: price-books
    description: Marketplace list-price markup rules
    x-group: Price Books
  - name: products
    description: Product CRUD, bulk import, and publish
    x-group: Products
  - name: promotions
    description: Central promotions and marketplace sync
    x-group: Promotions
  - name: public-agent
    description: Public agent discovery and catalog APIs
    x-group: Public Agent
  - name: settlements
    description: settlements
    x-group: Settlements
  - name: ucp
    description: Universal Commerce Protocol
    x-group: UCP
paths:
  /api/v1/search:
    post:
      tags:
        - public-agent
      summary: Search Public Merchant Products
      description: >-
        Search across all public merchants and products with optional merchant,
        pricing, stock, marketplace, and localization filters.
      operationId: post_v1_search
      parameters:
        - name: q
          in: query
          required: false
          description: Natural-language search query.
          schema:
            type: string
            maxLength: 300
        - name: category
          in: query
          required: false
          description: Optional category-name filter.
          schema:
            type: string
            maxLength: 120
        - name: brand
          in: query
          required: false
          description: Optional brand filter.
          schema:
            type: string
            maxLength: 120
        - name: min_price
          in: query
          required: false
          description: Minimum listed price.
          schema:
            type: number
        - name: max_price
          in: query
          required: false
          description: Maximum listed price.
          schema:
            type: number
        - name: in_stock
          in: query
          required: false
          description: Filter by stock availability.
          schema:
            type: boolean
        - name: merchant_ids
          in: query
          required: false
          description: Comma-separated merchant IDs to scope the search.
          schema:
            type: string
        - name: sort
          in: query
          required: false
          description: Sort order.
          schema:
            type: string
            enum:
              - relevance
              - price_asc
              - price_desc
            default: relevance
        - name: platform
          in: query
          required: false
          description: Marketplace platform filter.
          schema:
            type: string
            enum:
              - shopee
              - lazada
        - name: country
          in: query
          required: false
          description: 'Marketplace country hint (example: sg).'
          schema:
            type: string
        - name: language
          in: query
          required: false
          description: Localization language. Defaults to en.
          schema:
            type: string
            enum:
              - en
              - th
              - id
              - ms
              - vi
              - tl
            default: en
        - name: include_intent
          in: query
          required: false
          description: Include lightweight parsed query intent metadata.
          schema:
            type: boolean
        - name: limit
          in: query
          required: false
          description: Result limit (1..100). Defaults to 20.
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
        - name: offset
          in: query
          required: false
          description: Pagination offset (0..10000). Defaults to 0.
          schema:
            type: integer
            minimum: 0
            maximum: 10000
            default: 0
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  ok:
                    type: boolean
                  apiVersion:
                    type: string
                    default: public_search_v1
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '402':
          description: Insufficient Credits
        '403':
          description: Forbidden
        '500':
          description: Internal Server Error
      security: []

````