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

# Retrieve answers

Retrieve the AI-powered answers to questions for a given item. If the client accepts [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) (text/event-stream content) response will be streamed back, otherwise complete response JSON is returned.

# 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/item_questions/{question}/answer": {
      "get": {
        "tags": [
          "Results"
        ],
        "summary": "Retrieve answers",
        "description": "Retrieve the AI-powered answers to questions for a given item. If the client accepts [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events) (text/event-stream content) response will be streamed back, otherwise complete response JSON is returned.",
        "operationId": "v1-asa-retrieve-item-questions-answer",
        "parameters": [
          {
            "name": "question",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Question",
              "description": "The question provided by the user as free-form text."
            },
            "description": "The question provided by the user as free-form text."
          },
          {
            "name": "key",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Key",
              "description": "The key of the index to use."
            },
            "description": "The key of the index to use."
          },
          {
            "name": "item_id",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "title": "Item ID",
              "description": "The ID of the item to return answer(s) for."
            },
            "description": "The ID of the item to return answer(s) for."
          },
          {
            "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"
          },
          {
            "name": "variation_id",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "title": "Item variation ID",
              "description": "The ID of the variation of the item to return answer(s) for."
            },
            "description": "The ID of the variation of the item to return answer(s) for."
          },
          {
            "name": "guard",
            "in": "query",
            "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
            },
            "description": "Turn the content moderation check on or off. When on, shopper input is screened before the agent processes it."
          },
          {
            "name": "num_results",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "title": "Number of results",
              "description": "The number of answers to return."
            },
            "description": "The number of answers to return."
          },
          {
            "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": "AI-powered answer to question for a given item.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AsaItemQuestionsAnswerResponse"
                }
              },
              "text/event-stream": {
                "schema": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "event": {
                          "type": "string",
                          "default": "start"
                        },
                        "data": {
                          "$ref": "#/components/schemas/SSEItemQuestionsStart"
                        }
                      },
                      "required": [
                        "event",
                        "data"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "event": {
                          "type": "string",
                          "default": "end"
                        },
                        "data": {
                          "$ref": "#/components/schemas/SSEItemQuestionsEnd"
                        }
                      },
                      "required": [
                        "event",
                        "data"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "event": {
                          "type": "string",
                          "default": "server_error"
                        },
                        "data": {
                          "$ref": "#/components/schemas/SSEItemQuestionsServerError"
                        }
                      },
                      "required": [
                        "event",
                        "data"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "event": {
                          "type": "string",
                          "default": "message"
                        },
                        "data": {
                          "$ref": "#/components/schemas/SSEItemQuestionsMessage"
                        }
                      },
                      "required": [
                        "event",
                        "data"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "event": {
                          "type": "string",
                          "default": "follow_up_questions"
                        },
                        "data": {
                          "$ref": "#/components/schemas/SSEItemQuestionsFollowUpQuestions"
                        }
                      },
                      "required": [
                        "event",
                        "data"
                      ]
                    },
                    {
                      "type": "object",
                      "properties": {
                        "event": {
                          "type": "string",
                          "default": "item_results"
                        },
                        "data": {
                          "$ref": "#/components/schemas/SSEItemQuestionsItemResults"
                        }
                      },
                      "required": [
                        "event",
                        "data"
                      ]
                    }
                  ]
                },
                "examples": {
                  "Start": {
                    "summary": "Start",
                    "description": "Event always emitted on the beginning of the server-sent event stream.",
                    "value": "event: start\ndata: {'event': 'start', 'qna_result_id': 'string', 'thread_id': 'string'}"
                  },
                  "Message": {
                    "summary": "Message",
                    "description": "Event containing textual answer to the shopper's question.",
                    "value": "event: message\ndata: {'event': 'message', 'qna_result_id': 'string', 'thread_id': 'string', 'text': 'string'}"
                  },
                  "FollowUpQuestions": {
                    "summary": "Follow-up questions",
                    "description": "Event containing sequence of follow-up questions shopper might ask.",
                    "value": "event: follow_up_questions\ndata: {'event': 'follow_up_questions', 'qna_result_id': 'string', 'thread_id': 'string', 'questions': [{'value': 'string'}]"
                  },
                  "ItemResults": {
                    "summary": "Alternatives or complementary items",
                    "description": "Event containing sequence of alternative/complementary items.",
                    "value": "event: item_results\ndata: {'event': 'item_results', 'qna_result_id': 'string', 'thread_id': 'string', 'request': {}, 'response': {'results': [{'value': 'string', 'matched_terms': ['string'], 'data': {'id': 'string', 'url': 'string', 'image_url': 'string', 'variation_id': 'string', 'facets': [{'name': 'string', 'values': [0, 'string']}], 'groups': [{'group_id': 'string', 'display_name': 'string', 'path': '/great-grandparent/grandparent/parent/', 'path_list': [{'id': 'string', 'display_name': 'string'}]}]}, 'variations': [{'data': {'id': 'string', 'url': 'string', 'image_url': 'string', 'variation_id': 'string', 'facets': [{'name': 'string', 'values': [0, 'string']}], 'groups': [{'group_id': 'string', 'display_name': 'string', 'path': '/great-grandparent/grandparent/parent/', 'path_list': [{'id': 'string', 'display_name': 'string'}]}]}, 'value': 'string'}], 'variations_map': {}, 'additionalProp': {}}]}}"
                  },
                  "ServerError": {
                    "summary": "Server error",
                    "description": "Event indicating that the internal server error occurred while processing request.",
                    "value": "event: server_error\ndata: {'status_code': 500, 'message': 'Internal Server Error'}"
                  },
                  "Ping": {
                    "summary": "Ping",
                    "description": "Event sent periodically to the caller to keep connection alive and prevent timeouts.",
                    "value": "event: ping\ndata: {'time': '2025-06-02T00:00:00+01:00'}"
                  },
                  "End": {
                    "summary": "End",
                    "description": "Event always closing the stream of server-sent events.",
                    "value": "event: end\ndata: {'event': 'end', 'qna_result_id': 'string', 'thread_id': 'string'}"
                  }
                }
              }
            }
          },
          "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": {
      "HTTPValidationError": {
        "properties": {
          "detail": {
            "items": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "type": "array",
            "title": "Detail"
          }
        },
        "type": "object",
        "title": "HTTP validation error"
      },
      "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"
      },
      "Result": {
        "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": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/ResultVariation"
                },
                "type": "array"
              },
              {
                "type": "null"
              }
            ],
            "title": "Variations",
            "description": "An array of this item's variations matching user's query."
          },
          "variations_map": {
            "anyOf": [
              {
                "items": {},
                "type": "array"
              },
              {
                "type": "object"
              },
              {
                "type": "null"
              }
            ],
            "title": "Variations Map",
            "description": "Variations data in the format requested by `variations_map` query parameter."
          }
        },
        "additionalProperties": true,
        "type": "object",
        "required": [
          "value",
          "matched_terms",
          "data"
        ],
        "title": "Result"
      },
      "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"
      },
      "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"
      },
      "AsaItemQuestionsAnswerResponse": {
        "properties": {
          "qna_result_id": {
            "type": "string",
            "title": "QnA Result ID",
            "description": "Questions and answers result ID."
          },
          "value": {
            "type": "string",
            "title": "Value",
            "description": "AI-powered answer to question for a given item."
          },
          "item_results": {
            "$ref": "#/components/schemas/ItemQuestionsItemResults",
            "title": "Item results",
            "description": "Contains list of suggested items (alternatives, complementary items etc.)."
          },
          "follow_up_questions": {
            "items": {
              "$ref": "#/components/schemas/ItemQuestion"
            },
            "type": "array",
            "title": "Follow Up Questions",
            "description": "AI-powered list of follow-up questions for the given item."
          },
          "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."
          }
        },
        "type": "object",
        "required": [
          "qna_result_id",
          "value"
        ],
        "title": "Item questions answer response"
      },
      "SSEItemQuestionsStart": {
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "start"
            ],
            "title": "Event Type",
            "default": "start"
          },
          "qna_result_id": {
            "type": "string",
            "title": "QnA Result ID",
            "description": "Questions and answers result ID."
          },
          "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."
          }
        },
        "type": "object",
        "required": [
          "event",
          "qna_result_id"
        ],
        "title": "Start"
      },
      "SSEItemQuestionsEnd": {
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "end"
            ],
            "title": "Event Type",
            "default": "end"
          },
          "qna_result_id": {
            "type": "string",
            "title": "QnA Result ID",
            "description": "Questions and answers result ID."
          },
          "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."
          }
        },
        "type": "object",
        "required": [
          "event",
          "qna_result_id"
        ],
        "title": "End"
      },
      "SSEItemQuestionsServerError": {
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "server_error"
            ],
            "title": "Event Type",
            "default": "server_error"
          },
          "qna_result_id": {
            "type": "string",
            "title": "QnA Result ID",
            "description": "Questions and answers result ID."
          },
          "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."
          },
          "status_code": {
            "type": "integer",
            "title": "Status Code"
          },
          "message": {
            "type": "string",
            "title": "Message"
          }
        },
        "type": "object",
        "required": [
          "event",
          "qna_result_id",
          "status_code",
          "message"
        ],
        "title": "Server error"
      },
      "SSEItemQuestionsMessage": {
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "message"
            ],
            "title": "Event Type",
            "default": "message"
          },
          "qna_result_id": {
            "type": "string",
            "title": "QnA Result ID",
            "description": "Questions and answers result ID."
          },
          "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."
          },
          "text": {
            "type": "string",
            "title": "Text",
            "description": "Arbitrary text."
          }
        },
        "type": "object",
        "required": [
          "event",
          "qna_result_id"
        ],
        "title": "Message"
      },
      "SSEItemQuestionsFollowUpQuestions": {
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "follow_up_questions"
            ],
            "title": "Event Type",
            "default": "follow_up_questions"
          },
          "qna_result_id": {
            "type": "string",
            "title": "QnA Result ID",
            "description": "Questions and answers result ID."
          },
          "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."
          },
          "questions": {
            "items": {
              "$ref": "#/components/schemas/ItemQuestion"
            },
            "type": "array",
            "title": "Questions",
            "description": "AI-powered list of follow-up questions that user might ask."
          }
        },
        "type": "object",
        "required": [
          "event",
          "qna_result_id",
          "questions"
        ],
        "title": "Follow-up questions"
      },
      "SSEItemQuestionsItemResults": {
        "properties": {
          "event": {
            "type": "string",
            "enum": [
              "item_results"
            ],
            "title": "Event Type",
            "default": "item_results"
          },
          "qna_result_id": {
            "type": "string",
            "title": "QnA Result ID",
            "description": "Questions and answers result ID."
          },
          "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."
          },
          "request": {
            "type": "object",
            "title": "Request"
          },
          "response": {
            "$ref": "#/components/schemas/ItemQuestionsItemResultsResponse"
          }
        },
        "type": "object",
        "required": [
          "event",
          "qna_result_id",
          "response"
        ],
        "title": "Item results"
      },
      "ItemQuestion": {
        "properties": {
          "value": {
            "type": "string",
            "title": "Value",
            "description": "Human-readable question text."
          }
        },
        "type": "object",
        "required": [
          "value"
        ],
        "title": "Item question"
      },
      "ItemQuestionsItemResultsResponse": {
        "properties": {
          "results": {
            "items": {
              "$ref": "#/components/schemas/Result"
            },
            "type": "array",
            "title": "Results",
            "description": "List of results in format defined by Constructor product discovery API."
          }
        },
        "type": "object",
        "required": [
          "results"
        ],
        "title": "Item questions item results response"
      },
      "ItemQuestionsItemResults": {
        "properties": {
          "request": {
            "type": "object",
            "title": "Request"
          },
          "response": {
            "$ref": "#/components/schemas/ItemQuestionsItemResultsResponse"
          }
        },
        "type": "object",
        "required": [
          "response"
        ],
        "title": "Item questions item results"
      }
    }
  },
  "x-readme": {
    "explorer-enabled": false
  }
}
```