> ## 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. # Instant Search > Type-ahead search in a single call: products / collections / pages / articles + keyword suggestions + autocorrect, plus an empty-state trending block. Auth: `Authorization: Bearer ` + `x-shop`. ```json 200 - product_details view theme={null} { "query": "sho", "corrected_query": "shoe", "autocorrect": { "original_query": "sho", "corrected_query": "shoe", "confidence": 0.92, "corrections": [], "alternatives": [] }, "suggestions": [ { "text": "shoes", "type": "keyword", "object_count": 120, "search_count": 45 } ], "products": { "results": [ { "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" } ] } ], "total": 120 }, "collections": { "results": [ { "collection_id": 1, "title": "Shoes", "handle": "shoes", "image": null } ], "total": 3 }, "pages": { "results": [ { "page_id": 1, "title": "Size Guide", "handle": "size-guide" } ], "total": 1 }, "articles": { "results": [], "total": 0 }, "trending": { "searches": [], "products": [] }, "metadata": { "query_time": 12, "locale": "en-US", "market": null, "min_query_length": 2 } } ``` ```json 200 - empty query (trending) theme={null} { "query": "", "corrected_query": null, "autocorrect": null, "suggestions": [], "products": { "results": [], "total": 0 }, "collections": { "results": [], "total": 0 }, "pages": { "results": [], "total": 0 }, "articles": { "results": [], "total": 0 }, "trending": { "searches": [ { "term": "sale", "translated_term": "sale", "search_count": 300 } ], "products": [] }, "metadata": { "query_time": 8, "locale": "en-US", "market": null, "min_query_length": 2 } } ``` ```json 400 theme={null} { "error": [ { "message": "\"limit\" must be less than or equal to 100", "path": ["limit"], "type": "number.max", "context": { "limit": 100, "value": 500, "label": "limit", "key": "limit" } } ], "ok": false } ``` ## OpenAPI ````yaml POST /api/storefront/v1/headless/instant-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/instant-search: servers: - url: https://search.glood.ai post: description: >- Type-ahead search in a single call: products / collections / pages / articles + keyword suggestions + autocorrect, plus an empty-state trending block. Auth: `Authorization: Bearer ` + `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/HeadlessInstantSearchRequest' responses: '200': description: Instant search results content: application/json: schema: $ref: '#/components/schemas/HeadlessInstantSearchResponse' '400': description: Validation or shop error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: HeadlessInstantSearchRequest: type: object description: >- Instant search request. Union of the legacy instant-results, instant-suggest and trending inputs. properties: query: type: string description: >- Search term. Required but may be an empty string (empty / too-short queries return the `trending` block). default: '' example: sho locale: type: string description: BCP-47 locale. default: en-US market: type: integer description: Shopify market id. limit: type: integer description: Per-type result limit. minimum: 1 maximum: 100 objects: type: array description: >- Which result blocks to return. Defaults to `config.instant_search_objects`. `query_suggestion`/`auto_suggestion` -> keyword suggestions; `autocorrect` -> spell-correct. items: type: string enum: - product - collection - page - article - blog - query_suggestion - auto_suggestion - autocorrect view: type: string description: Product render mode. enum: - product_details - product_ids default: product_details trending: type: object description: Options for the empty-state trending block. properties: type: type: string description: Which trending blocks to populate. enum: - searches - products - all default: searches period: type: string description: Trending time window. enum: - 1h - 24h - 7d - 30d default: 7d category: type: string description: Optional category filter for trending. limit: type: integer description: Max trending items. minimum: 1 maximum: 100 default: 20 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. HeadlessInstantSearchResponse: type: object description: >- Instant search results: products / collections / pages / articles + suggestions + autocorrect + trending. properties: query: type: string description: Echo of the requested query. corrected_query: type: string nullable: true description: >- Convenience mirror of `autocorrect.corrected_query`; null when no correction. autocorrect: nullable: true allOf: - type: object description: Spell-correction result. properties: original_query: type: string description: The query as sent. corrected_query: type: string description: The spell-corrected query. confidence: type: number description: Correction confidence 0-1. corrections: type: array description: Per-token corrections. items: type: object alternatives: type: array description: Alternative corrected queries. items: type: object description: Spell-correction result, or null when not requested / disabled. suggestions: type: array description: Keyword suggestions. items: type: object description: A keyword suggestion. properties: text: type: string description: Suggested keyword. type: type: string description: Suggestion type (e.g. `keyword`). object_count: type: integer nullable: true description: Number of objects matching this suggestion. search_count: type: integer nullable: true description: How often this term has been searched. products: type: object description: Product results block. properties: results: type: array description: Product objects (or `{ product_id }` when `view=product_ids`). items: $ref: '#/components/schemas/HeadlessProduct' total: type: integer description: Total matching products. collections: type: object description: Collection results block. properties: results: type: array description: Matching collections. items: type: object description: A collection result. properties: collection_id: type: integer description: Collection id. title: type: string description: Collection title. handle: type: string description: Collection handle. image: type: object nullable: true description: Collection image, or null. total: type: integer description: Total matching collections. pages: type: object description: Page results block. properties: results: type: array description: Matching pages. items: type: object description: A page result. properties: page_id: type: integer description: Page id. title: type: string description: Page title. handle: type: string description: Page handle. total: type: integer description: Total matching pages. articles: type: object description: Article results block. properties: results: type: array description: Matching blog articles. items: type: object description: An article result. properties: article_id: type: integer description: Article id. title: type: string description: Article title. handle: type: string description: Article handle. blog_handle: type: string description: Parent blog handle. author: type: string description: Article author. summary: type: string description: Article summary/excerpt. image: type: object nullable: true description: Article image, or null. published_at: type: string description: ISO publish timestamp. tags: type: array description: Article tags. items: type: string total: type: integer description: Total matching articles. trending: nullable: true allOf: - type: object description: Trending block. properties: searches: type: array description: Trending search terms. items: type: object description: A trending search. properties: term: type: string description: Trending term. translated_term: type: string description: Localised term. search_count: type: integer description: Search volume for the term. products: type: array description: Trending product objects. items: $ref: '#/components/schemas/HeadlessProduct' description: >- Populated only when the query is empty / below the minimum length; otherwise empty arrays. metadata: type: object description: Response metadata. properties: query_time: type: integer description: Server processing time in ms. locale: type: string description: Resolved locale. market: type: integer nullable: true description: Echoed market id. min_query_length: type: integer description: Minimum query length before non-trending results are returned. 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 ````