---
updatedAt: 2026-05-28T22:56:10.000Z
agentTools:
  projectIndex: https://docs.constructor.com/llms.txt
---

# Retrieve by intent

Retrieve AI-powered product discovery suggestions based on conversational free-form text. Returns results in small batches using a real-time [Server-sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) stream for a dynamic user experience.

# OpenAPI definition

```json
{
  "openapi": "3.1.0",
  "info": {
    "title": "AI Shopping Agent",
    "summary": "AI Shopping Agent",
    "description": "API documentation for the AI shopping and product insights agent.",
    "version": "v1",
    "contact": {
      "email": "support@constructor.io"
    }
  },
  "servers": [
    {
      "url": "https://agent.cnstrc.com"
    }
  ],
  "security": [],
  "tags": [
    {
      "name": "Results",
      "description": "AI-powered shopping and product insight results."
    }
  ],
  "paths": {
    "/v1/intent/{query}": {
      "get": {
        "tags": [
          "Results"
        ],
        "summary": "Retrieve by intent",
        "description": "Retrieve AI-powered product discovery suggestions based on conversational free-form text. Returns results in small batches using a real-time [Server-sent Events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) stream for a dynamic user experience.",
        "operationId": "v1-asa-retrieve-intent",
        "parameters": [
          {
            "description": "The query provided by the user as free-form text.",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Intent",
              "description": "The query provided by the user as free-form text."
            },
            "name": "query",
            "in": "path"
          },
          {
            "description": "The key of the index to use.",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Key",
              "description": "The key of the index to use."
            },
            "name": "key",
            "in": "query"
          },
          {
            "description": "A unique identifier for the conversation thread. This ID links multiple requests to the same conversation.",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid",
              "title": "Thread ID",
              "description": "A unique identifier for the conversation thread. This ID links multiple requests to the same conversation."
            },
            "name": "thread_id",
            "in": "query"
          },
          {
            "description": "A URL-encoded JSON string containing filters (inaccessible to end users) used to narrow the result set. Applied before filters accessible to end users. Does not affect facet counts. Only results that match the filters are returned. More details on https://docs.constructor.com/reference/shared-pre-filter-expressions",
            "required": false,
            "schema": {
              "type": "string",
              "title": "Pre Filter Expression",
              "description": "A URL-encoded JSON string containing filters (inaccessible to end users) used to narrow the result set. Applied before filters accessible to end users. Does not affect facet counts. Only results that match the filters are returned. More details on https://docs.constructor.com/reference/shared-pre-filter-expressions"
            },
            "name": "pre_filter_expression",
            "in": "query"
          },
          {
            "description": "The domain specifying a set of specific instructions for processing the intent, e.g., 'recipes', 'sportsgear'.",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Domain",
              "description": "The domain specifying a set of specific instructions for processing the intent, e.g., 'recipes', 'sportsgear'."
            },
            "name": "domain",
            "in": "query"
          },
          {
            "description": "Turn the content moderation check on or off. When on, shopper input is screened before the agent processes it.",
            "required": false,
            "schema": {
              "type": "boolean",
              "title": "Guard",
              "description": "Turn the content moderation check on or off. When on, shopper input is screened before the agent processes it.",
              "default": false
            },
            "name": "guard",
            "in": "query"
          },
          {
            "description": "The maximum number of result events to return.",
            "required": false,
            "schema": {
              "type": "integer",
              "title": "Num Result Events",
              "description": "The maximum number of result events to return."
            },
            "name": "num_result_events",
            "in": "query"
          },
          {
            "description": "**Deprecated. Please, use `num_results_per_event` instead.**",
            "required": false,
            "schema": {
              "type": "integer",
              "title": "Num Results Per Page",
              "description": "**Deprecated. Please, use `num_results_per_event` instead.**"
            },
            "name": "num_results_per_page",
            "in": "query",
            "deprecated": true
          },
          {
            "description": "The maximum number of results to return per `search_result` event.",
            "required": false,
            "schema": {
              "type": "integer",
              "title": "Num Results Per Event",
              "description": "The maximum number of results to return per `search_result` event."
            },
            "name": "num_results_per_event",
            "in": "query"
          },
          {
            "description": "An object containing options to format different aspects of the response.",
            "required": false,
            "schema": {
              "title": "Fmt Options",
              "description": "An object containing options to format different aspects of the response.",
              "allOf": [
                {
                  "$ref": "#/components/schemas/FmtOptions"
                }
              ]
            },
            "style": "deepObject",
            "explode": true,
            "name": "fmt_options",
            "in": "query"
          },
          {
            "description": "A URL-encoded JSON string. More details on https://docs.constructor.com/reference/search-search-results#using-the-qs-parameter",
            "required": false,
            "schema": {
              "type": "string",
              "title": "Qs",
              "description": "A URL-encoded JSON string. More details on https://docs.constructor.com/reference/search-search-results#using-the-qs-parameter"
            },
            "name": "qs",
            "in": "query"
          },
          {
            "description": "The ID of the client and version that the request is coming from, such as `cio-js-2.90`.",
            "required": false,
            "schema": {
              "type": "string",
              "title": "C",
              "description": "The ID of the client and version that the request is coming from, such as `cio-js-2.90`."
            },
            "name": "c",
            "in": "query"
          },
          {
            "description": "A customer defined context (such as `vip-club-member`) used to evaluate redirect or refined tag rules. Pass multiple segments by passing multiple `us` arguments.",
            "required": false,
            "schema": {
              "items": {
                "type": "string"
              },
              "type": "array",
              "title": "User segments",
              "description": "A customer defined context (such as `vip-club-member`) used to evaluate redirect or refined tag rules. Pass multiple segments by passing multiple `us` arguments."
            },
            "name": "us",
            "in": "query"
          },
          {
            "description": "A customer generated anonymized identifier for a user on a customer website. It should only be sent for logged in customers and helps constructor to tie multiple client and session ID's together to form a behavioral data profile across devices.",
            "required": false,
            "schema": {
              "type": "string",
              "title": "User ID",
              "description": "A customer generated anonymized identifier for a user on a customer website. It should only be sent for logged in customers and helps constructor to tie multiple client and session ID's together to form a behavioral data profile across devices."
            },
            "name": "ui",
            "in": "query"
          },
          {
            "description": "An integer representing the user's session number (starting with `1`), incremented after a 30 minute period of inactivity.",
            "required": false,
            "schema": {
              "type": "integer",
              "title": "S",
              "description": "An integer representing the user's session number (starting with `1`), incremented after a 30 minute period of inactivity."
            },
            "name": "s",
            "in": "query"
          },
          {
            "description": "A globally unique identifier for the user browser (or mobile application instance) making the request.",
            "required": false,
            "schema": {
              "type": "string",
              "title": "I",
              "description": "A globally unique identifier for the user browser (or mobile application instance) making the request."
            },
            "name": "i",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "SSE stream containing a series of events with discovered items or AI generated textual messages.",
            "content": {
              "text/event-stream": {
                "schema": {
                  "anyOf": [
                    {
                      "properties": {
                        "event": {
                          "type": "string",
                          "default": "start"
                        },
                        "data": {
                          "$ref": "#/components/schemas/SSEIntentStart"
                        }
                      },
                      "type": "object",
                      "required": [
                        "event",
                        "data"
                      ]
                    },
                    {
                      "properties": {
                        "event": {
                          "type": "string",
                          "default": "end"
                        },
                        "data": {
                          "$ref": "#/components/schemas/SSEIntentEnd"
                        }
                      },
                      "type": "object",
                      "required": [
                        "event",
                        "data"
                      ]
                    },
                    {
                      "properties": {
                        "event": {
                          "type": "string",
                          "default": "server_error"
                        },
                        "data": {
                          "$ref": "#/components/schemas/SSEIntentServerError"
                        }
                      },
                      "type": "object",
                      "required": [
                        "event",
                        "data"
                      ]
                    },
                    {
                      "properties": {
                        "event": {
                          "type": "string",
                          "default": "message"
                        },
                        "data": {
                          "$ref": "#/components/schemas/SSEIntentMessage"
                        }
                      },
                      "type": "object",
                      "required": [
                        "event",
                        "data"
                      ]
                    },
                    {
                      "properties": {
                        "event": {
                          "type": "string",
                          "default": "image_meta"
                        },
                        "data": {
                          "$ref": "#/components/schemas/SSEIntentImageMeta"
                        }
                      },
                      "type": "object",
                      "required": [
                        "event",
                        "data"
                      ]
                    },
                    {
                      "properties": {
                        "event": {
                          "type": "string",
                          "default": "article_reference"
                        },
                        "data": {
                          "$ref": "#/components/schemas/SSEIntentArticleReference"
                        }
                      },
                      "type": "object",
                      "required": [
                        "event",
                        "data"
                      ]
                    },
                    {
                      "properties": {
                        "event": {
                          "type": "string",
                          "default": "search_result"
                        },
                        "data": {
                          "$ref": "#/components/schemas/SSEIntentSearchResult"
                        }
                      },
                      "type": "object",
                      "required": [
                        "event",
                        "data"
                      ]
                    },
                    {
                      "properties": {
                        "event": {
                          "type": "string",
                          "default": "follow_up_refinement"
                        },
                        "data": {
                          "$ref": "#/components/schemas/SSEIntentFollowUpRefinement"
                        }
                      },
                      "type": "object",
                      "required": [
                        "event",
                        "data"
                      ]
                    },
                    {
                      "properties": {
                        "event": {
                          "type": "string",
                          "default": "recipe_info"
                        },
                        "data": {
                          "$ref": "#/components/schemas/SSEIntentRecipeInfo"
                        }
                      },
                      "type": "object",
                      "required": [
                        "event",
                        "data"
                      ]
                    },
                    {
                      "properties": {
                        "event": {
                          "type": "string",
                          "default": "recipe_instructions"
                        },
                        "data": {
                          "$ref": "#/components/schemas/SSEIntentRecipeInstructions"
                        }
                      },
                      "type": "object",
                      "required": [
                        "event",
                        "data"
                      ]
                    }
                  ]
                },
                "examples": {
                  "Message": {
                    "summary": "Message",
                    "description": "Represents a simple text message. Usually emitted prior to the one or multiple search_result events, giving textual explanation why are those results relevant to the shopper. Can contain a question for the shopper, asking for clarification or suggesting follow-up queries to further refine result set.",
                    "value": "event: message\ndata: {'event': 'message', 'intent_result_id': 'abcd1234-56ef-7890-ab12-1234567890ab', 'text': 'A collection of refreshing summer recipes.'}"
                  },
                  "CustomerSupportMessage": {
                    "summary": "Customer support message",
                    "description": "A message that answers a customer support question. `route` is set to `customer_support`.",
                    "value": "event: message\ndata: {\"intent_result_id\": \"abcd1234-56ef-7890-ab12-1234567890ab\", \"text\": \"For help with your order, please contact customer support.\", \"route\": \"customer_support\"}"
                  },
                  "ImageMeta": {
                    "summary": "Image meta",
                    "description": "",
                    "value": "event: image_meta\ndata: {'event': 'image_meta', 'intent_result_id': 'def01234-56ab-7890-cd12-1234567890ef', 'item_id': 'item12345', 'image_url': 'https://example.com/images/item12345.jpg', 'image_url_small': 'https://example.com/images/item12345-small.jpg'}"
                  },
                  "ArticleReference": {
                    "summary": "Article reference",
                    "description": "",
                    "value": "event: article_reference\ndata: {'event': 'article_reference', 'intent_result_id': '987fbc77-34ae-11d1-a456-426655440000', 'source': 'https://example.com/article/how-to-cook-rice', 'title': 'How to Cook Rice Perfectly Every Time', 'image_url': 'https://example.com/images/cooked-rice.jpg', 'abstract': 'Discover the secrets to cooking fluffy, perfect rice every time with our simple guide.'}"
                  },
                  "SearchResult": {
                    "summary": "Search result",
                    "description": "An event carrying the product results the agent selected for this response.",
                    "value": "event: search_result\ndata: {'event': 'search_result', 'intent_result_id': 'abc12345-6789-de01-2345-6789abcdef01', 'result_id': 'res12345-6789-de01-2345-6789abcdef01', 'response': {'search_request': {'display_name': 'Italian', 'search_term': 'best Italian recipes', 'params': {'cuisine': 'Italian', 'difficulty': 'easy'}}, 'alternative_search_requests': [{'display_name': 'Vegetarian Italian', 'search_term': 'vegetarian Italian recipes', 'params': {'cuisine': 'Italian', 'difficulty': 'easy', 'diet': 'vegetarian'}}, {'display_name': 'Quick Italian', 'search_term': 'quick Italian recipes', 'params': {'cuisine': 'Italian', 'difficulty': 'easy', 'time': '<30min'}}], 'results': ['...']}}"
                  },
                  "FollowUpRefinement": {
                    "summary": "Follow-up refinement",
                    "description": "Suggested refinement options for the follow-up question asked by the agent. Each option is a short label the shopper can select to narrow their intent.",
                    "value": "event: follow_up_refinement\ndata: {'event': 'follow_up_refinement', 'intent_result_id': 'abcd1234-56ef-7890-ab12-1234567890ab', 'question': 'Do you have any color preference?', 'options': ['Blue', 'Red', 'Green']}"
                  },
                  "RecipeInfo": {
                    "summary": "Recipe info",
                    "description": "An event that represents recipes' auxiliary information like cooking times & serving sizes.",
                    "value": "event: recipe_info\ndata: {'event': 'recipe_info', 'intent_result_id': '123e4567-e89b-12d3-a456-426614174000', 'recipe_title': 'Classic Tomato Spaghetti', 'prep_time_minutes': 10, 'cook_time_minutes': 20, 'number_of_servings': 4, 'ingredients': ['400g spaghetti', '1 garlic clove', '400g tin of tomatoes', 'Handful of basil leaves']}"
                  },
                  "RecipeInstructions": {
                    "summary": "Recipe instructions",
                    "description": "Step-by-step preparation instructions.",
                    "value": "event: recipe_instructions\ndata: {'event': 'recipe_instructions', 'intent_result_id': '123e4567-e89b-12d3-a456-426614174000', 'steps': ['Boil water in a large pot.', 'Add spaghetti and cook for 8-10 minutes or until al dente; drain.', 'In a large skillet, cook garlic in olive oil over medium heat until lightly golden.', 'Stir in tomatoes, and cook until heated through.', 'Mix spaghetti with the sauce, and serve with basil leaves on top.'], 'text': 'Serve with grated Parmesan cheese if desired.'}"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid request parameters."
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HTTPValidationError"
                }
              }
            }
          },
          "500": {
            "description": "Internal server error."
          }
        },
        "security": []
      }
    }
  },
  "components": {
    "schemas": {
      "SSEIntentArticleReference": {
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "article_reference"
            ],
            "title": "Event Type",
            "default": "article_reference"
          },
          "intent_result_id": {
            "type": "string",
            "title": "Intent Result ID"
          },
          "thread_id": {
            "type": "string",
            "format": "uuid",
            "title": "Thread ID"
          },
          "source": {
            "type": "string",
            "maxLength": 2083,
            "minLength": 1,
            "format": "uri",
            "title": "Article URL"
          },
          "title": {
            "type": "string",
            "title": "Title"
          },
          "image_url": {
            "type": "string",
            "maxLength": 2083,
            "minLength": 1,
            "format": "uri",
            "title": "Image URL"
          },
          "abstract": {
            "type": "string",
            "title": "Abstract"
          }
        },
        "type": "object",
        "required": [
          "intent_result_id",
          "source",
          "title"
        ],
        "title": "Article reference",
        "example": {
          "event": "article_reference",
          "intent_result_id": "987fbc77-34ae-11d1-a456-426655440000",
          "source": "https://example.com/article/how-to-cook-rice",
          "title": "How to Cook Rice Perfectly Every Time",
          "image_url": "https://example.com/images/cooked-rice.jpg",
          "abstract": "Discover the secrets to cooking fluffy, perfect rice every time with our simple guide."
        }
      },
      "IntentRequest": {
        "properties": {
          "intent": {
            "type": "string",
            "title": "Intent",
            "description": "The query provided by the user as free-form text."
          },
          "key": {
            "type": "string",
            "title": "Key",
            "description": "The key of the index to use."
          },
          "domain": {
            "type": "string",
            "title": "Domain",
            "description": "The domain specifying a set of specific instructions for processing the intent, e.g., 'recipes', 'sportsgear'."
          },
          "thread_id": {
            "type": "string",
            "format": "uuid",
            "title": "Thread ID",
            "description": "A unique identifier for the conversation thread. This ID links multiple requests to the same conversation."
          },
          "num_results_per_page": {
            "type": "integer",
            "title": "Num Results Per Page",
            "description": "The maximum number of results to return per `search_result` event.",
            "default": 20
          },
          "num_result_events": {
            "type": "integer",
            "title": "Num Result Events",
            "description": "The maximum number of result events to return."
          },
          "c": {
            "type": "string",
            "title": "C",
            "description": "The ID of the client and version that the request is coming from, such as `cio-js-2.90`."
          },
          "ui": {
            "type": "string",
            "title": "Ui",
            "description": "A customer generated anonymized identifier for a user on a customer website. It should only be sent for logged in customers and helps constructor to tie multiple client and session ID's together to form a behavioral data profile across devices."
          },
          "us": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Us",
            "description": "A customer defined context (such as `vip-club-member`) used to evaluate redirect or refined tag rules. Pass multiple segments by passing multiple `us` arguments."
          },
          "s": {
            "type": "integer",
            "title": "S",
            "description": "An integer representing the user's session number (starting with `1`), incremented after a 30 minute period of inactivity."
          },
          "i": {
            "type": "string",
            "title": "I",
            "description": "A globally unique identifier for the user browser (or mobile application instance) making the request."
          },
          "qs": {
            "type": "object",
            "title": "Qs",
            "description": "A dictionary of additional query parameters to pass to the search and browse client."
          },
          "pre_filter_expression": {
            "$ref": "#/components/schemas/DictOrJsonStringWithDict",
            "title": "Pre Filter Expression",
            "description": "An object containing any number of filters (inaccessible to end users) used to narrow the result set. Applied before filters accessible to end users. Does not affect facet counts. Only results that match the filters are returned."
          }
        },
        "type": "object",
        "required": [
          "intent",
          "key",
          "domain"
        ],
        "title": "Intent request"
      },
      "DictOrJsonStringWithDict": {
        "anyOf": [
          {
            "type": "object"
          },
          {
            "type": "string",
            "format": "json",
            "title": "Encoded JSON String"
          }
        ],
        "title": "Mapping or JSON string",
        "description": "Model that accepts either a dictionary or a JSON string that contains a dictionary."
      },
      "SSEIntentEnd": {
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "end"
            ],
            "title": "Event Type",
            "default": "end"
          },
          "intent_result_id": {
            "type": "string",
            "title": "Intent Result ID"
          },
          "thread_id": {
            "type": "string",
            "format": "uuid",
            "title": "Thread ID"
          },
          "search_result_count": {
            "type": "integer",
            "title": "Search Result Count",
            "description": "The number of search result events returned."
          }
        },
        "type": "object",
        "required": [
          "intent_result_id"
        ],
        "title": "End"
      },
      "SSEIntentMessage": {
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "message"
            ],
            "title": "Event Type",
            "default": "message"
          },
          "intent_result_id": {
            "type": "string",
            "title": "Intent Result ID"
          },
          "thread_id": {
            "type": "string",
            "format": "uuid",
            "title": "Thread ID"
          },
          "text": {
            "type": "string",
            "title": "Text",
            "description": "Arbitrary text."
          },
          "route": {
            "$ref": "#/components/schemas/MessageRoute",
            "description": "Marks a customer support answer. `text` contains the full answer, including replies from your support agent. You can use `route` to show a button for your support chat or help center. Applies to this message only; the next message is handled as usual. Omitted for other messages. New values may be added without an API version change. Treat unknown values as if `route` were absent."
          }
        },
        "type": "object",
        "required": [
          "intent_result_id"
        ],
        "title": "Message",
        "description": "Represents a simple text message.",
        "examples": [
          {
            "event": "message",
            "intent_result_id": "abcd1234-56ef-7890-ab12-1234567890ab",
            "text": "Arbitrary text."
          },
          {
            "event": "message",
            "intent_result_id": "abcd1234-56ef-7890-ab12-1234567890ab",
            "text": "For help with your order, please contact customer support.",
            "route": "customer_support"
          }
        ]
      },
      "MessageRoute": {
        "type": "string",
        "enum": [
          "customer_support"
        ],
        "title": "Message route",
        "description": "Where the client should send the shopper next. `customer_support` marks a customer support answer."
      },
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTP validation error"
      },
      "SSEIntentImageMeta": {
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "image_meta"
            ],
            "title": "Event Type",
            "default": "image_meta"
          },
          "intent_result_id": {
            "type": "string",
            "title": "Intent Result ID"
          },
          "thread_id": {
            "type": "string",
            "format": "uuid",
            "title": "Thread ID"
          },
          "item_id": {
            "type": "string",
            "title": "Item ID"
          },
          "image_url": {
            "type": "string",
            "maxLength": 2083,
            "minLength": 1,
            "format": "uri",
            "title": "Image URL"
          },
          "image_url_small": {
            "type": "string",
            "maxLength": 2083,
            "minLength": 1,
            "format": "uri",
            "title": "Small image URL"
          }
        },
        "type": "object",
        "required": [
          "intent_result_id",
          "item_id"
        ],
        "title": "Image meta",
        "example": {
          "event": "image_meta",
          "intent_result_id": "def01234-56ab-7890-cd12-1234567890ef",
          "item_id": "item12345",
          "image_url": "https://example.com/images/item12345.jpg",
          "image_url_small": "https://example.com/images/item12345-small.jpg"
        }
      },
      "Path": {
        "properties": {
          "id": {
            "type": "string",
            "title": "ID",
            "description": "The ID of the group."
          },
          "display_name": {
            "type": "string",
            "title": "Display Name",
            "description": "The name of the group as it is displayed to end users."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "id"
        ],
        "title": "Path"
      },
      "SSEIntentRecipeInfo": {
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "recipe_info"
            ],
            "title": "Event Type",
            "default": "recipe_info"
          },
          "intent_result_id": {
            "type": "string",
            "title": "Intent Result ID"
          },
          "thread_id": {
            "type": "string",
            "format": "uuid",
            "title": "Thread ID"
          },
          "recipe_title": {
            "type": "string",
            "title": "Recipe Title"
          },
          "prep_time_minutes": {
            "type": "integer",
            "title": "Preparation time in minutes"
          },
          "cook_time_minutes": {
            "type": "integer",
            "title": "Cooking time in minutes"
          },
          "number_of_servings": {
            "type": "integer",
            "title": "Number of servings"
          },
          "ingredients": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Ingredients"
          }
        },
        "type": "object",
        "required": [
          "intent_result_id",
          "recipe_title",
          "prep_time_minutes",
          "cook_time_minutes",
          "ingredients"
        ],
        "title": "Recipe info",
        "description": "An event that represents recipes' auxiliary information like cooking times & serving sizes.",
        "example": {
          "event": "recipe_info",
          "intent_result_id": "123e4567-e89b-12d3-a456-426614174000",
          "recipe_title": "Classic Tomato Spaghetti",
          "prep_time_minutes": 10,
          "cook_time_minutes": 20,
          "number_of_servings": 4,
          "ingredients": [
            "400g spaghetti",
            "1 garlic clove",
            "400g tin of tomatoes",
            "Handful of basil leaves"
          ]
        }
      },
      "SSEIntentRecipeInstructions": {
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "recipe_instructions"
            ],
            "title": "Event Type",
            "default": "recipe_instructions"
          },
          "intent_result_id": {
            "type": "string",
            "title": "Intent Result ID"
          },
          "thread_id": {
            "type": "string",
            "format": "uuid",
            "title": "Thread ID"
          },
          "steps": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Recipe Directions"
          },
          "text": {
            "type": "string",
            "title": "Text",
            "description": "Arbitrary optional text"
          }
        },
        "type": "object",
        "required": [
          "intent_result_id",
          "steps"
        ],
        "title": "Recipe instructions",
        "description": "Step-by-step preparation instructions.",
        "example": {
          "event": "recipe_instructions",
          "intent_result_id": "123e4567-e89b-12d3-a456-426614174000",
          "steps": [
            "Boil water in a large pot.",
            "Add spaghetti and cook for 8-10 minutes or until al dente; drain.",
            "In a large skillet, cook garlic in olive oil over medium heat until lightly golden.",
            "Stir in tomatoes, and cook until heated through.",
            "Mix spaghetti with the sauce, and serve with basil leaves on top."
          ],
          "text": "Serve with grated Parmesan cheese if desired."
        }
      },
      "IntentSearchResultResponse": {
        "properties": {
          "search_request": {
            "$ref": "#/components/schemas/IntentSearchRequest",
            "description": "The search or browse request that produced these results. Omitted when the results come from recommendations."
          },
          "alternative_search_requests": {
            "items": {
              "$ref": "#/components/schemas/IntentSearchRequest"
            },
            "type": "array",
            "title": "Alternative Search Requests",
            "description": "Other searches the shopper can run. Omitted when the results come from recommendations."
          },
          "results": {
            "items": {
              "$ref": "#/components/schemas/SearchandizedResult"
            },
            "type": "array",
            "title": "Results"
          }
        },
        "type": "object",
        "required": [
          "results"
        ],
        "title": "Intent search result response"
      },
      "FmtOptions": {
        "properties": {
          "fields": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 300
            },
            "maxItems": 20,
            "title": "Fields",
            "description": "A list of specific item fields to return in the response. Allows the request to control which fields are returned."
          },
          "show_hidden_fields": {
            "type": "boolean",
            "title": "Show Hidden Fields",
            "description": "A flag to return all `hidden` fields in the response.",
            "default": false
          },
          "hidden_fields": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 300
            },
            "maxItems": 30,
            "title": "Hidden Fields",
            "description": "A list of specific hidden fields to return in the response. Unlike `show_hidden_fields` this parameter allows the request to control which `hidden` fields are returned. Used to return item fields for a particular store or user segment."
          },
          "variations_return_type": {
            "allOf": [
              {
                "$ref": "#/components/schemas/VariationsReturnType"
              }
            ],
            "title": "Variations Return Type",
            "description": "A flag to return `default`, `all`, or `matched` variations."
          },
          "groups_max_depth": {
            "type": "integer",
            "title": "Groups Max Depth",
            "description": "The maximum depth of the group hierarchy in the response.",
            "default": 1
          },
          "groups_start": {
            "type": "string",
            "title": "Groups Start",
            "description": "A flag to specify the start of the group hierarchy returned in the response. `current` returns groups starting from the currently selected one. `top` returns groups starting from the root category in the hierarchy. `group_id:{id}`, returns the whole tree starting from group with the provided id.",
            "default": "current"
          },
          "groups_path": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            },
            "maxItems": 10,
            "title": "Groups Path",
            "description": "Specifies the path from the root group to the current group you are browsing. It is used to construct the parents path in the `response.groups` for the current browsed group. Max depth allowed for the path is 10. This option is only accepted when `groups_start` is 'current'."
          },
          "groups_sort_by": {
            "allOf": [
              {
                "$ref": "#/components/schemas/GroupsSortOrder"
              }
            ],
            "title": "Groups Sort By",
            "description": "A string indicating the option to sort results by. Sorting options are created from item fields and facets in the product catalog."
          },
          "groups_sort_order": {
            "allOf": [
              {
                "$ref": "#/components/schemas/SortOrderType"
              }
            ],
            "description": "A flag to sort either `ascending` or `descending`."
          },
          "show_hidden_facets": {
            "type": "boolean",
            "title": "Show Hidden Facets",
            "description": "A flag to return all facets configured as `hidden` in `response.facets`.",
            "default": false
          },
          "hidden_facets": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            },
            "maxItems": 50,
            "title": "Hidden Facets",
            "description": "A list of specific hidden facets to return in the response. Unlike `show_hidden_facets` this parameter allows the request to control which hidden facets are returned. Used to return facets for a particular store or user segment."
          },
          "show_hidden_facet_options": {
            "type": "boolean",
            "title": "Show Hidden Facet Options",
            "description": "A flag to return all `hidden` facets options in the response."
          },
          "show_protected_facets": {
            "type": "boolean",
            "title": "Show Protected Facets",
            "description": "A flag to return all `protected` facets in the response. Requires authentication.",
            "default": false
          },
          "facet_options": {
            "type": "object",
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1,
                "maxLength": 100
              },
              "maxItems": 15
            },
            "title": "Facet Options",
            "description": "A list of specific facet options per facet to return in the response. This parameter accepts up to 5 facets and works only with facets of type `multiple`. Invalid facet options will be ignored. Used to return facet options for a particular facet like store or user segment."
          },
          "facet_groups_limit": {
            "type": "integer",
            "title": "Facet Groups Limit",
            "description": "The maximum limit of the facet groups returned in the response.",
            "minimum": 0
          },
          "show_hidden_sort_options": {
            "type": "boolean",
            "title": "Show Hidden Sort Options",
            "description": "A flag to return all sort options configured as `hidden` in `response.sort_options`."
          },
          "hidden_sort_options": {
            "type": "array",
            "items": {
              "type": "string",
              "minLength": 1,
              "maxLength": 100
            },
            "maxItems": 25,
            "title": "Hidden Sort Options",
            "description": "A list of `sort_by` fields whose hidden sort options should be included in the response. Unlike `show_hidden_sort_options` this parameter allows you to specify exactly which hidden sort options are returned."
          }
        },
        "additionalProperties": true,
        "type": "object",
        "title": "Format options",
        "description": "Options to format different aspects of the response."
      },
      "VariationsReturnType": {
        "type": "string",
        "enum": [
          "default",
          "all",
          "matched"
        ],
        "title": "Variations return type"
      },
      "GroupsSortOrder": {
        "type": "string",
        "enum": [
          "relevance",
          "value",
          "num_matches"
        ],
        "title": "Groups sort order"
      },
      "SortOrderType": {
        "type": "string",
        "enum": [
          "ascending",
          "descending"
        ],
        "title": "Sort order type"
      },
      "ResultData": {
        "properties": {
          "id": {
            "type": "string",
            "title": "ID",
            "description": "The ID of this item as specified in the catalog."
          },
          "url": {
            "type": "string",
            "title": "URL",
            "description": "The URL where the item can be viewed or purchased."
          },
          "image_url": {
            "type": "string",
            "title": "Image URL",
            "description": "The item's image URL for display in results."
          },
          "variation_id": {
            "type": "string",
            "title": "Variation ID",
            "description": "ID of the selected (best matching) variation. All metadata of the best matching variation will also be merged into the item's `data` object. Returned when [item variation](#) data is defined."
          },
          "facets": {
            "items": {
              "$ref": "#/components/schemas/ResultFacet"
            },
            "type": "array",
            "title": "Facets",
            "description": "The item's associated facets."
          },
          "groups": {
            "items": {
              "$ref": "#/components/schemas/ResultGroup"
            },
            "type": "array",
            "title": "Groups",
            "description": "The item's associated categories."
          }
        },
        "type": "object",
        "title": "Result data"
      },
      "ResultFacet": {
        "properties": {
          "name": {
            "type": "string",
            "title": "Name"
          },
          "values": {
            "items": {
              "anyOf": [
                {
                  "type": "number"
                },
                {
                  "type": "integer"
                },
                {
                  "type": "string"
                }
              ]
            },
            "type": "array",
            "title": "Values"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "name",
          "values"
        ],
        "title": "Result facet"
      },
      "ResultGroup": {
        "properties": {
          "group_id": {
            "type": "string",
            "title": "Group ID",
            "description": "The ID of the group."
          },
          "display_name": {
            "type": "string",
            "title": "Display Name",
            "description": "The name of the group as it is displayed to end users."
          },
          "path": {
            "type": "string",
            "title": "Path",
            "description": "The path of `group_id`s above this group. `/great-grandparent/grandparent/parent/`",
            "example": "/great-grandparent/grandparent/parent/"
          },
          "path_list": {
            "items": {
              "$ref": "#/components/schemas/Path"
            },
            "type": "array",
            "title": "Path List",
            "description": "An array of groups constituting the path."
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "group_id",
          "path",
          "path_list"
        ],
        "title": "Result group"
      },
      "ResultVariation": {
        "properties": {
          "data": {
            "$ref": "#/components/schemas/ResultData"
          },
          "value": {
            "type": "string",
            "title": "Value"
          }
        },
        "additionalProperties": false,
        "type": "object",
        "required": [
          "data",
          "value"
        ],
        "title": "Result variation"
      },
      "SSEIntentSearchResult": {
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "search_result"
            ],
            "title": "Event Type",
            "default": "search_result"
          },
          "intent_result_id": {
            "type": "string",
            "title": "Intent Result ID"
          },
          "thread_id": {
            "type": "string",
            "format": "uuid",
            "title": "Thread ID"
          },
          "result_id": {
            "type": "string",
            "title": "Result ID"
          },
          "response": {
            "$ref": "#/components/schemas/IntentSearchResultResponse"
          }
        },
        "type": "object",
        "required": [
          "intent_result_id",
          "result_id",
          "response"
        ],
        "title": "Search result",
        "description": "An event carrying the product results the agent selected for this response.",
        "example": {
          "event": "search_result",
          "intent_result_id": "abc12345-6789-de01-2345-6789abcdef01",
          "result_id": "res12345-6789-de01-2345-6789abcdef01",
          "response": {
            "search_request": {
              "display_name": "Italian",
              "search_term": "best Italian recipes",
              "params": {
                "cuisine": "Italian",
                "difficulty": "easy"
              }
            },
            "alternative_search_requests": [
              {
                "display_name": "Vegetarian Italian",
                "search_term": "vegetarian Italian recipes",
                "params": {
                  "cuisine": "Italian",
                  "difficulty": "easy",
                  "diet": "vegetarian"
                }
              },
              {
                "display_name": "Quick Italian",
                "search_term": "quick Italian recipes",
                "params": {
                  "cuisine": "Italian",
                  "difficulty": "easy",
                  "time": "<30min"
                }
              }
            ],
            "results": [
              "..."
            ]
          }
        }
      },
      "SSEIntentFollowUpRefinement": {
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "follow_up_refinement"
            ],
            "title": "Event Type",
            "default": "follow_up_refinement"
          },
          "intent_result_id": {
            "type": "string",
            "title": "Intent Result ID"
          },
          "thread_id": {
            "type": "string",
            "format": "uuid",
            "title": "Thread ID"
          },
          "question": {
            "type": "string",
            "title": "Follow-Up Question",
            "description": "The follow-up question these options answer."
          },
          "options": {
            "anyOf": [
              {
                "items": {
                  "type": "string"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Suggested answers to the follow-up question",
            "description": "Suggested answer options for the follow-up question. May be null if no predefined options are available."
          }
        },
        "type": "object",
        "required": [
          "intent_result_id",
          "question"
        ],
        "title": "Follow-up refinement",
        "description": "Suggested refinement options for the follow-up question asked by the agent. Each option is a short label the shopper can select to narrow their intent.",
        "example": {
          "event": "follow_up_refinement",
          "intent_result_id": "abcd1234-56ef-7890-ab12-1234567890ab",
          "question": "Do you have any color preference?",
          "options": [
            "Blue",
            "Red",
            "Green"
          ]
        }
      },
      "IntentSearchRequest": {
        "properties": {
          "display_name": {
            "type": "string",
            "title": "Display Name"
          },
          "search_term": {
            "type": "string",
            "title": "Search Term"
          },
          "params": {
            "type": "object",
            "title": "Params"
          }
        },
        "type": "object",
        "required": [
          "display_name",
          "search_term",
          "params"
        ],
        "title": "Intent search request"
      },
      "SearchandizedResult": {
        "properties": {
          "value": {
            "type": "string",
            "title": "Value",
            "description": "Name of the matched item or variation (if variations are defined)."
          },
          "matched_terms": {
            "items": {
              "type": "string"
            },
            "type": "array",
            "title": "Matched Terms",
            "description": "All terms within the item matching the user's query (regardless of whether misspelled)."
          },
          "data": {
            "$ref": "#/components/schemas/ResultData"
          },
          "variations": {
            "items": {
              "$ref": "#/components/schemas/ResultVariation"
            },
            "type": "array",
            "title": "Variations",
            "description": "An array of this item's variations matching user's query."
          },
          "variations_map": {
            "anyOf": [
              {
                "items": {},
                "type": "array"
              },
              {
                "type": "object"
              }
            ],
            "title": "Variations Map",
            "description": "Variations data in the format requested by `variations_map` query parameter."
          },
          "is_slotted": {
            "type": "boolean",
            "title": "Is Slotted",
            "description": "`true` if the current product is slotted as a result of searchandizing."
          },
          "labels": {
            "type": "object",
            "title": "Labels",
            "description": "A set of miscellaneous properties of this result. For example, it can indicate whether a slotted result is advertised or promoted."
          }
        },
        "type": "object",
        "required": [
          "value",
          "matched_terms",
          "data",
          "is_slotted",
          "labels"
        ],
        "title": "Searchandized result"
      },
      "SSEIntentServerError": {
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "server_error"
            ],
            "title": "Event Type",
            "default": "server_error"
          },
          "intent_result_id": {
            "type": "string",
            "title": "Intent Result ID"
          },
          "thread_id": {
            "type": "string",
            "format": "uuid",
            "title": "Thread ID"
          },
          "status_code": {
            "type": "integer",
            "title": "Status Code"
          },
          "message": {
            "type": "string",
            "title": "Message"
          }
        },
        "type": "object",
        "required": [
          "intent_result_id",
          "status_code",
          "message"
        ],
        "title": "Server error"
      },
      "SSEIntentStart": {
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "start"
            ],
            "title": "Event Type",
            "default": "start"
          },
          "intent_result_id": {
            "type": "string",
            "title": "Intent Result ID"
          },
          "thread_id": {
            "type": "string",
            "format": "uuid",
            "title": "Thread ID"
          },
          "request": {
            "$ref": "#/components/schemas/IntentRequest"
          }
        },
        "type": "object",
        "required": [
          "intent_result_id",
          "request"
        ],
        "title": "Start"
      },
      "ValidationError": {
        "properties": {
          "loc": {
            "items": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "integer"
                }
              ]
            },
            "type": "array",
            "title": "Location"
          },
          "msg": {
            "type": "string",
            "title": "Message"
          },
          "type": {
            "type": "string",
            "title": "Error Type"
          }
        },
        "type": "object",
        "required": [
          "loc",
          "msg",
          "type"
        ],
        "title": "Validation error"
      }
    }
  },
  "x-readme": {
    "explorer-enabled": false
  }
}
```