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

# Search

> Full product search (hybrid text + vector) with applied facets, sort, page-based pagination and optional inline aggregations. Auth: `Authorization: Bearer <gl_sf_...>` + `x-shop`.

<ResponseExample>
  ```json 200 - product_details view theme={null}
  {
    "status": "ok",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "products": [
      {
        "product_id": 9311227838783,
        "title": "Running Shoe",
        "handle": "running-shoe",
        "product_type": "Shoes",
        "vendor": "Acme",
        "tags": ["sale", "summer"],
        "price": 49.99,
        "compare_at_price": 69.99,
        "display_price": 49.99,
        "display_compare_at_price": 69.99,
        "display_currency": "USD",
        "original_currency": "USD",
        "currency_rate": 1,
        "available_for_sale": true,
        "is_in_stock": true,
        "total_inventory": 42,
        "image": { "id": "gid://shopify/ProductImage/1", "url": "https://cdn.shopify.com/s/files/1/shoe.jpg", "width": 800, "height": 800, "alt_text": "Running Shoe" },
        "featured_media": null,
        "media": [],
        "options": [ { "id": 111, "name": "Size", "position": 1, "values": ["S", "M", "L"] } ],
        "variants": [
          {
            "variant_id": 456,
            "title": "M",
            "display_name": "Running Shoe - M",
            "sku": "RS-M",
            "position": 1,
            "price": 49.99,
            "compare_at_price": 69.99,
            "available_for_sale": true,
            "is_in_stock": true,
            "sellable_online_quantity": 10,
            "selected_options": [ { "name": "Size", "value": "M" } ],
            "image": null
          }
        ],
        "metafields": [ { "namespace": "custom", "key": "material", "value": "leather" } ]
      }
    ],
    "pagination": {
      "total": 240, "page": 1, "limit": 20, "total_pages": 12,
      "has_next_page": true, "has_prev_page": false, "next_page": 2, "prev_page": null
    },
    "facets": [
      {
        "key": "color",
        "type": "terms",
        "aggregation": { "buckets": [ { "value": "red", "count": 42, "selected": true } ] }
      }
    ],
    "metadata": { "query_time": 40, "total_time": 55, "region": "toronto", "search_type": "hybrid" }
  }
  ```

  ```json 200 - product_ids view theme={null}
  {
    "status": "ok",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "products": [ { "product_id": 9311227838783 }, { "product_id": 9311227838784 } ],
    "pagination": {
      "total": 240, "page": 1, "limit": 20, "total_pages": 12,
      "has_next_page": true, "has_prev_page": false, "next_page": 2, "prev_page": null
    },
    "facets": [],
    "metadata": { "query_time": 38, "total_time": 41, "region": "toronto", "search_type": "hybrid" }
  }
  ```

  ```json 400 theme={null}
  {
    "error": [
      {
        "message": "\"sort\" must be one of [relevance, title_asc, title_desc, price_asc, price_desc, best_selling, oldest, newest, collection_default]",
        "path": ["sort"],
        "type": "any.only",
        "context": { "label": "sort", "key": "sort" }
      }
    ],
    "ok": false
  }
  ```
</ResponseExample>


## OpenAPI

````yaml POST /api/storefront/v1/headless/search
openapi: 3.0.1
info:
  title: Glood.AI API Reference
  description: Glood.AI API Reference
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://storefront.glood.ai
security:
  - bearerAuth: []
paths:
  /api/storefront/v1/headless/search:
    servers:
      - url: https://search.glood.ai
    post:
      description: >-
        Full product search (hybrid text + vector) with applied facets, sort,
        page-based pagination and optional inline aggregations. Auth:
        `Authorization: Bearer <gl_sf_...>` + `x-shop`.
      parameters:
        - name: x-shop
          in: header
          description: >-
            Shopify store URL. Resolves the shop for the request (headless does
            not accept `?shop=`).
          required: true
          schema:
            type: string
            example: shop.myshopify.com
      requestBody:
        description: Request body
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeadlessSearchRequest'
      responses:
        '200':
          description: Search results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HeadlessSearchResponse'
        '400':
          description: Validation or shop error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    HeadlessSearchRequest:
      type: object
      description: >-
        Full product search (hybrid text + vector) with applied facets, sort,
        pagination and optional inline aggregations.
      properties:
        query:
          type: string
          description: Search term. May be empty.
          default: ''
          example: running shoe
        target_page:
          type: string
          description: Search context.
          enum:
            - search
            - collection
          default: search
        target_id:
          type: integer
          description: Target object id (e.g. collection id) when scoping to a collection.
        locale:
          type: string
          description: BCP-47 locale.
          default: en-US
        market:
          type: integer
          description: Shopify market id.
        facets:
          type: array
          description: Applied filters.
          items:
            type: object
            description: An applied facet.
            required:
              - key
              - value
            properties:
              key:
                type: string
                description: Filter key.
              operator:
                type: string
                description: Combine operator.
                enum:
                  - equals
                  - contains
                  - between
                  - or
                  - and
                  - in
                default: or
              value:
                type: array
                description: Selected value(s).
                items:
                  oneOf:
                    - type: string
                    - type: number
                    - type: boolean
        sort:
          type: string
          description: >-
            Result ordering. Omit it to use the resolved default: the sort
            configured for this collection if the merchant set one, otherwise
            the shop-wide default, otherwise `relevance` — the same value the
            config endpoint returns as `default_ordering`. `collection_default`
            reproduces the product order the merchant arranged on the collection
            in Shopify; it needs `target_page: "collection"` with a `target_id`
            and falls back to `relevance` without one. Collection positions are
            refreshed by the collection sync, so a product added or reordered
            since the last sync is ordered last until the next one.
          enum:
            - relevance
            - title_asc
            - title_desc
            - price_asc
            - price_desc
            - best_selling
            - oldest
            - newest
            - collection_default
            - name_asc
            - name_desc
            - bestselling
            - created_asc
            - created_desc
        view:
          type: string
          description: Product render mode.
          enum:
            - product_details
            - product_ids
          default: product_details
        pagination:
          type: object
          description: Page-based pagination.
          properties:
            page:
              type: integer
              description: 1-based page number.
              minimum: 1
              default: 1
            limit:
              type: integer
              description: Page size.
              minimum: 1
              maximum: 100
              default: 20
        options:
          type: object
          description: Search options.
          properties:
            include_aggregations:
              type: boolean
              description: Compute and return inline facet aggregations.
              default: false
            include_highlights:
              type: boolean
              description: Include search highlights.
              default: false
            include_facets:
              type: boolean
              description: Include inline facets (implies aggregations).
              default: false
            boost_in_stock:
              type: boolean
              description: Boost in-stock products.
              default: true
            personalize:
              type: boolean
              description: >-
                Apply personalization (requires config +
                visitor_id/customer_id).
              default: false
        visitor_id:
          type: string
          description: >-
            Anonymous device/browser UID (the `gl_s_uid` cookie). The primary
            personalization key; stays stable when a customer logs in.
        client_id:
          type: string
          description: Per-session / per-device identifier.
        customer_id:
          type: string
          description: >-
            Shopify customer id. Present only when the shopper is logged in;
            enables customer-level personalization.
    HeadlessSearchResponse:
      type: object
      description: >-
        Product search results with pagination, optional inline facets and
        metadata.
      properties:
        status:
          type: string
          description: Response status.
          example: ok
        request_id:
          type: string
          description: Unique id for this search serve (use for attribution events).
          format: uuid
        products:
          type: array
          description: Product objects (or `{ product_id }` when `view=product_ids`).
          items:
            $ref: '#/components/schemas/HeadlessProduct'
        pagination:
          type: object
          description: Page-based pagination.
          properties:
            total:
              type: integer
              description: Total matching products.
            page:
              type: integer
              description: Current page.
            limit:
              type: integer
              description: Page size.
            total_pages:
              type: integer
              description: Total pages.
            has_next_page:
              type: boolean
              description: Whether a next page exists.
            has_prev_page:
              type: boolean
              description: Whether a previous page exists.
            next_page:
              type: integer
              nullable: true
              description: Next page number, or null.
            prev_page:
              type: integer
              nullable: true
              description: Previous page number, or null.
        facets:
          type: array
          description: >-
            Inline facet aggregations. Present only when
            `include_aggregations`/`include_facets` was requested.
          items:
            type: object
            description: An inline facet.
            properties:
              key:
                type: string
                description: Filter key.
              type:
                type: string
                description: Aggregation type.
                enum:
                  - terms
                  - range
              aggregation:
                type: object
                description: Aggregation payload.
                properties:
                  buckets:
                    type: array
                    description: Aggregated buckets.
                    items:
                      type: object
                      description: An inline facet bucket.
                      properties:
                        value:
                          type: string
                          description: Bucket value.
                        count:
                          type: integer
                          description: Match count.
                        selected:
                          type: boolean
                          description: Whether this value is currently applied.
                  min:
                    type: number
                    description: Range minimum (range facets).
                  max:
                    type: number
                    description: Range maximum (range facets).
                  count:
                    type: integer
                    description: Matched docs (range facets).
        metadata:
          type: object
          description: Response metadata.
          properties:
            query_time:
              type: integer
              description: Search time in ms.
            total_time:
              type: integer
              description: Total request time in ms.
            region:
              type: string
              description: Data-plane region.
              example: toronto
            search_type:
              type: string
              description: Engine used.
              example: hybrid
    Error:
      required:
        - error
        - message
      type: object
      properties:
        error:
          type: integer
          format: int32
        message:
          type: string
    HeadlessProduct:
      type: object
      properties:
        product_id:
          type: integer
          description: Unique identifier of the product
        title:
          type: string
          description: Title of the product
        price:
          type: number
          description: Minimum variant price for the product
        tags:
          oneOf:
            - type: string
            - type: array
              items:
                type: string
          description: >-
            Product tags. Recommendations return a comma-separated string;
            search returns an array of strings.
        product_type:
          type: string
          description: Type/category of the product
        vendor:
          type: string
          description: Vendor/brand of the product
        image:
          type: object
          properties:
            id:
              type: string
            url:
              type: string
            height:
              type: integer
            width:
              type: integer
            altText:
              type: string
        handle:
          type: string
          description: URL handle/slug for the product
        compare_at_price:
          type: number
          description: Original/compare-at price of the product
        options:
          type: array
          items:
            type: object
            properties:
              id:
                type: integer
              name:
                type: string
                description: Option name (e.g. Size, Color)
              values:
                type: array
                items:
                  type: string
              position:
                type: integer
        variants:
          type: array
          items:
            $ref: '#/components/schemas/HeadlessProductVariant'
        metafields:
          oneOf:
            - type: object
              description: Key-value map (recommendations).
            - type: array
              items:
                type: object
                description: A metafield.
                properties:
                  namespace:
                    type: string
                    description: Metafield namespace.
                  key:
                    type: string
                    description: Metafield key.
                  value:
                    type: string
                    description: Metafield value.
          description: >-
            Product metafields. Recommendations return a key-value map; search
            returns a list of `{ namespace, key, value }`.
        display_price:
          type: number
          nullable: true
          description: >-
            Currency-converted price for the requested market (search). Falls
            back to `price`.
        display_compare_at_price:
          type: number
          nullable: true
          description: Currency-converted compare-at price for the market (search).
        display_currency:
          type: string
          description: Currency code the display prices are expressed in (search).
        original_currency:
          type: string
          description: Shop's original currency code (search).
        currency_rate:
          type: number
          description: Conversion rate applied to derive display prices (search).
        available_for_sale:
          type: boolean
          description: Whether the product has any variant available for sale (search).
        is_in_stock:
          type: boolean
          description: Whether the product has any in-stock variant (search).
        total_inventory:
          type: integer
          nullable: true
          description: Total inventory across variants (search).
        featured_media:
          type: object
          nullable: true
          description: Featured media object (search).
        media:
          type: array
          description: Product media objects (search).
          items:
            type: object
    HeadlessProductVariant:
      type: object
      properties:
        variant_id:
          type: integer
          description: Unique identifier of the variant
        title:
          type: string
          description: Title of the variant
        display_name:
          type: string
          description: Human-readable display name of the variant
        position:
          type: integer
          description: Display order position of the variant
        sku:
          type: string
          description: Stock keeping unit identifier
        selected_options:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Option name
              value:
                type: string
                description: Selected value
        price:
          oneOf:
            - type: string
            - type: number
          nullable: true
          description: >-
            Variant price. Recommendations return a decimal string; search
            returns a number.
        compare_at_price:
          oneOf:
            - type: string
            - type: number
          nullable: true
          description: >-
            Variant compare-at price. String (recommendations) or number
            (search); null when unset.
        image:
          type: object
          properties:
            id:
              type: string
            url:
              type: string
            height:
              type: integer
            width:
              type: integer
            altText:
              type: string
        sellable_online_quantity:
          type: integer
          description: Quantity available for online sale
        is_in_stock:
          type: boolean
          description: Whether the variant is currently in stock
        available_for_sale:
          type: boolean
          description: Whether the variant is available for purchase
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````