openapi: 3.2.0 info: title: Constructorio Results API version: '1.0' description: 'Operations tagged Results across 2 of this provider''s published API definitions: constructorio-ai-shopping-agent-openapi.yml, constructorio-quizzes-openapi.yml. Each path carries the servers of the definition it was published in.' servers: - url: https://agent.cnstrc.com - url: https://quizzes.cnstrc.com tags: - name: Results paths: /v1/intent/{query}: get: tags: - Results summary: Retrieve by intent description: Retrieves 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: Enable or disable the moderation check. required: false schema: type: boolean title: Guard description: Enable or disable the moderation check. 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: 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. 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: 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. name: ui in: query - description: An integer representing the users 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 users 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/Start' type: object required: - event - data - properties: event: type: string default: end data: $ref: '#/components/schemas/End' type: object required: - event - data - properties: event: type: string default: server_error data: $ref: '#/components/schemas/ServerError' type: object required: - event - data - properties: event: type: string default: message data: $ref: '#/components/schemas/Message' type: object required: - event - data - properties: event: type: string default: image_meta data: $ref: '#/components/schemas/ImageMeta' type: object required: - event - data - properties: event: type: string default: article_reference data: $ref: '#/components/schemas/ArticleReference' type: object required: - event - data - properties: event: type: string default: search_result data: $ref: '#/components/schemas/SSESearchResponse' type: object required: - event - data - properties: event: type: string default: follow_up_refinement data: $ref: '#/components/schemas/SSEFollowUpRefinement' type: object required: - event - data - properties: event: type: string default: recipe_info data: $ref: '#/components/schemas/RecipeInfo' type: object required: - event - data - properties: event: type: string default: recipe_instructions data: $ref: '#/components/schemas/RecipeInstructions' 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 data: {''event'': ''message'', ''intent_result_id'': ''abcd1234-56ef-7890-ab12-1234567890ab'', ''text'': ''A collection of refreshing summer recipes.''}' ImageMeta: summary: ImageMeta description: '' value: 'event: image_meta data: {''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: ArticleReference description: '' value: 'event: article_reference data: {''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.''}' SSESearchResponse: summary: SSESearchResponse description: An Event to encapsulate a SABR result. value: 'event: search_result data: {''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'': [''...'']}}' SSEFollowUpRefinement: summary: SSEFollowUpRefinement 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 data: {''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: RecipeInfo description: An event that represents recipes' auxiliary information like cooking times & serving sizes. value: 'event: recipe_info data: {''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: RecipeInstructions description: Step-by-step preparation instructions. value: 'event: recipe_instructions data: {''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: [] servers: - url: https://agent.cnstrc.com /v1/item_questions: get: tags: - Results summary: Retrieve questions description: Retrieves AI powered list of frequently asked questions for the given item. operationId: v1-asa-retrieve-item-questions parameters: - 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 questions for. description: The id of the item to return questions for. - name: variation_id in: query required: false schema: anyOf: - type: string - type: 'null' title: Item variation ID description: The id of the variation of the item to return questions for. description: The id of the variation of the item to return questions for. - name: num_results in: query required: false schema: anyOf: - type: integer - type: 'null' title: Number of results description: The number of questions to return. description: The number of questions 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: 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. 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: 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. name: ui in: query - description: An integer representing the users 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 users 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 list of frequently asked questions for the given item. content: application/json: schema: $ref: '#/components/schemas/pdp__schema__item_questions_api_model__AsaItemQuestionsResponse' '400': description: Invalid request parameters. '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '500': description: Internal server error. security: [] servers: - url: https://agent.cnstrc.com /v1/item_questions/{question}/answer: get: tags: - Results summary: Retrieves answers description: Retrieves 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: Enable or disable the moderation check. default: false description: Enable or disable the moderation check. - 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: 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. 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: 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. name: ui in: query - description: An integer representing the users 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 users 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/pdp__schema__item_questions_api_model__AsaItemQuestionsAnswerResponse' text/event-stream: schema: anyOf: - type: object properties: event: type: string default: start data: $ref: '#/components/schemas/pdp__schema__item_questions_api_model__Start' required: - event - data - type: object properties: event: type: string default: end data: $ref: '#/components/schemas/pdp__schema__item_questions_api_model__End' required: - event - data - type: object properties: event: type: string default: server_error data: $ref: '#/components/schemas/pdp__schema__item_questions_api_model__ServerError' required: - event - data - type: object properties: event: type: string default: message data: $ref: '#/components/schemas/pdp__schema__item_questions_api_model__Message' required: - event - data - type: object properties: event: type: string default: follow_up_questions data: $ref: '#/components/schemas/pdp__schema__item_questions_api_model__SSEFollowUpQuestions' required: - event - data - type: object properties: event: type: string default: item_results data: $ref: '#/components/schemas/pdp__schema__item_questions_api_model__SSEItemResults' required: - event - data examples: Start: summary: Start description: Event always emitted on the beginning of the server-sent event stream. value: 'event: start data: {''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 data: {''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 data: {''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 data: {''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 data: {''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 data: {''time'': ''2025-06-02T00:00:00+01:00''}' End: summary: End description: Event always closing the stream of server-sent events. value: 'event: end data: {''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: [] servers: - url: https://agent.cnstrc.com /v1/quizzes/{id}/next: get: operationId: v1-quizzes-get-next-question summary: Next question description: Retrieve the next question given a list of answers. If no answers are specified, it will return the first question. Use a `version_id` to retrieve the next question for a specific version of the quiz. security: [] parameters: - name: id required: true in: path description: The id of the quiz schema: type: string - name: key required: true in: query description: Index key for the customer's product catalog schema: type: string - name: section required: false in: query description: The section of the index to use. Defaults to `products`. schema: type: string - name: quiz_session_id required: false in: query description: Specific quiz session id for the quiz. Session id will be automatically assigned if it is not specified. schema: type: string - name: quiz_version_id required: false in: query description: Specific version id for the quiz. schema: type: string - name: version_id required: false in: query description: Specific version id for the quiz. Deprecated, please use `quiz_version_id` instead. schema: type: string - name: a required: false in: query description: A list of answers in the format ?a=,&a= where multiple options for a single answer are supplied in the same answer parameter (separated by ",") and options for the next question are supplied in the next answer parameter. schema: type: array items: type: string responses: '200': description: OK - Everything worked as expected. content: application/json: schema: $ref: '#/components/schemas/NextQuestion' '400': description: Bad Request - The request was unacceptable, often due to missing a required parameter. content: application/json: schema: type: object properties: error: description: Error code for easier categorization. type: string message: description: Human-readable error message describing the issue. type: string '404': description: Not Found - The resource you are looking for cannot be found. content: application/json: schema: type: object properties: error: description: Error code for easier categorization. type: string message: description: Human-readable error message describing the issue. type: string '500': description: Internal Server Error - Something went wrong on Constructor's end (these are rare). content: application/json: schema: type: object properties: error: description: Error code for easier categorization. type: string message: description: Human-readable error message describing the issue. type: string tags: - Results servers: - url: https://quizzes.cnstrc.com /v1/quizzes/{id}/results: get: operationId: v1-quizzes-get-quiz-results summary: Get results description: Retrieve AI optimized quiz results for products (or optionally other sections). security: [] parameters: - name: id required: true in: path description: The id of the quiz schema: type: string - name: key required: true in: query description: Index key for the customer's product catalog schema: type: string - name: section required: false in: query description: The section of the index to use. Defaults to `products`. schema: type: string - name: quiz_session_id required: false in: query description: Specific quiz session id for the quiz. Session id will be automatically assigned if it is not specified. schema: type: string - name: quiz_version_id required: false in: query description: Specific version id for the quiz. schema: type: string - name: version_id required: false in: query description: Specific version id for the quiz. Deprecated, please use `quiz_version_id` instead. schema: type: string - name: filters[] required: false in: query description: 'Any number of criteria by which you''d like to narrow the result set. This might be by color, size, or category (group) an item belongs to. Facets can be used as filters. Filters with the same key are ''OR''ed together, while filters with different keys are ''AND''ed together by default. If value has the form ''-'', it''s interpreted as a range (e.g: ''filters[Price]=100-200'' will match all items with ''Price'' from ''100'' to ''200'').' schema: type: string - name: num_results_per_page required: false in: query description: Specifies the number of results returned in each request. Defaults to 20 if not specified. schema: type: string - name: page required: false in: query description: Specifies the page number of the result to be fetched. Defaults to 1 if not specified. schema: type: string - name: a required: true in: query description: A list of answers in the format ?a=,&a= where multiple options for a single answer are supplied in the same answer parameter (separated by ",") and options for the next question are supplied in the next answer parameter. schema: type: array items: type: string responses: '200': description: OK - Everything worked as expected. content: application/json: schema: $ref: '#/components/schemas/Results' '400': description: Bad Request - The request was unacceptable, often due to missing a required parameter. content: application/json: schema: type: object properties: error: description: Error code for easier categorization. type: string message: description: Human-readable error message describing the issue. type: string '404': description: Not Found - The resource you are looking for cannot be found. content: application/json: schema: type: object properties: error: description: Error code for easier categorization. type: string message: description: Human-readable error message describing the issue. type: string '500': description: Internal Server Error - Something went wrong on Constructor's end (these are rare). content: application/json: schema: type: object properties: error: description: Error code for easier categorization. type: string message: description: Human-readable error message describing the issue. type: string tags: - Results servers: - url: https://quizzes.cnstrc.com /v1/quizzes/{id}/results_config: get: operationId: v1-quizzes-get-quiz-results-config summary: Get results page config description: Retrieve results page configuration security: [] parameters: - name: id required: true in: path description: The id of the quiz schema: type: string - name: key required: true in: query description: Index key for the customer's product catalog schema: type: string - name: section required: false in: query description: The section of the index to use. Defaults to `products`. schema: type: string - name: quiz_version_id required: false in: query description: Specific version id for the quiz. schema: type: string responses: '200': description: OK - Everything worked as expected. content: application/json: schema: $ref: '#/components/schemas/ResultsConfigResponse' '400': description: Bad Request - The request was unacceptable, often due to missing a required parameter. content: application/json: schema: type: object properties: error: description: Error code for easier categorization. type: string message: description: Human-readable error message describing the issue. type: string '404': description: Not Found - The resource you are looking for cannot be found. content: application/json: schema: type: object properties: error: description: Error code for easier categorization. type: string message: description: Human-readable error message describing the issue. type: string '500': description: Internal Server Error - Something went wrong on Constructor's end (these are rare). content: application/json: schema: type: object properties: error: description: Error code for easier categorization. type: string message: description: Human-readable error message describing the issue. type: string tags: - Results servers: - url: https://quizzes.cnstrc.com components: schemas: AsaRequest: 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 users 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: AsaRequest pdp__schema__item_questions_api_model__ServerError: 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: ServerError ResultVariation: properties: data: $ref: '#/components/schemas/ResultData' value: type: string title: Value additionalProperties: false type: object required: - data - value title: ResultVariation 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: SearchandizedResult pdp__schema__item_questions_api_model__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/pdp__schema__item_questions_api_model__ItemResults' title: Item results description: Contains list of suggested items (alternatives, complimentary items etc.). follow_up_questions: items: $ref: '#/components/schemas/pdp__schema__item_questions_api_model__Question' 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: AsaItemQuestionsAnswerResponse GroupsSortOrder: type: string enum: - relevance - value - num_matches title: GroupsSortOrder 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 SSESearchResponse: 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/Response' type: object required: - intent_result_id - result_id - response title: Base Result Event description: An Event to encapsulate a SABR result. 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: - '...' 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 pdp__schema__item_questions_api_model__Start: 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 pdp__schema__item_questions_api_model__Question: properties: value: type: string title: Value description: Human-readable question text. type: object required: - value title: Question 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: ResultFacet RecipeInfo: 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: RecipeInfo 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 Message: 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: Arbitrary text type: object required: - intent_result_id title: Message description: Represents a simple text message. example: event: message intent_result_id: abcd1234-56ef-7890-ab12-1234567890ab text: Arbitrary text. ArticleReference: 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: ArticleReference 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. 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: 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: ResultGroup ServerError: 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: ServerError End: 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 SSEFollowUpRefinement: 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 Event 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 pdp__schema__item_questions_api_model__AsaItemQuestionsResponse: properties: questions: items: $ref: '#/components/schemas/pdp__schema__item_questions_api_model__Question' type: array title: Questions description: AI powered list of frequently asked questions for the given item. type: object required: - questions title: AsaItemQuestionsResponse DictOrJsonStringWithDict: anyOf: - type: object - type: string format: json title: Encoded JSON String title: DictOrJsonStringWithDict description: Model that accepts either a dictionary or a JSON string that contains a dictionary. pdp__schema__item_questions_api_model__Message: 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 VariationsReturnType: type: string enum: - default - all - matched title: VariationsReturnType RecipeInstructions: 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: RecipeInstructions 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. 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: FmtOptions description: Options to format different aspects of the response. HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError 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: ValidationError pdp__schema__item_questions_api_model__Response: 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: Response pdp__schema__item_questions_api_model__SSEItemResults: 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/pdp__schema__item_questions_api_model__Response' type: object required: - event - qna_result_id - response title: SSEItemResults SearchRequest: 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: SearchRequest Start: 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/AsaRequest' type: object required: - intent_result_id - request title: Start 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 pdp__schema__item_questions_api_model__ItemResults: properties: request: type: object title: Request response: $ref: '#/components/schemas/pdp__schema__item_questions_api_model__Response' type: object required: - response title: ItemResults pdp__schema__item_questions_api_model__End: 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 SortOrderType: type: string enum: - ascending - descending title: SortOrderType pdp__schema__item_questions_api_model__SSEFollowUpQuestions: 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/pdp__schema__item_questions_api_model__Question' 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: SSEFollowUpQuestions Response: properties: search_request: $ref: '#/components/schemas/SearchRequest' alternative_search_requests: items: $ref: '#/components/schemas/SearchRequest' type: array title: Alternative Search Requests results: items: $ref: '#/components/schemas/SearchandizedResult' type: array title: Results type: object required: - search_request - alternative_search_requests - results title: Response ImageMeta: 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: image_url_small type: object required: - intent_result_id - item_id title: ImageMeta 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 Option: type: object properties: id: type: number value: type: string example: OPTION_VALUE attribute: type: - object - 'null' description: Attribute filter expression associated with this option. example: name: TEST_FILTER_NAME value: TEST_FILTER_VALUE images: type: - object - 'null' description: Image fields required for rendering the images at the option level on the front-end. allOf: - $ref: '#/components/schemas/Images' key: type: string description: Unique immutable key to identify the option MultipleSelectQuestion: type: object properties: id: type: number title: type: string example: TITLE description: type: - string - 'null' example: DESCRIPTION images: type: - object - 'null' allOf: - $ref: '#/components/schemas/Images' cta_text: type: - string - 'null' key: type: string is_skippable: type: boolean priority: type: - number - 'null' bucket_id: type: - string - 'null' option: type: array items: $ref: '#/components/schemas/Option' type: type: string enum: - multiple MultipleFilterSelectQuestion: type: object properties: id: type: number title: type: string example: TITLE description: type: - string - 'null' example: DESCRIPTION images: type: - object - 'null' allOf: - $ref: '#/components/schemas/Images' cta_text: type: - string - 'null' key: type: string is_skippable: type: boolean priority: type: - number - 'null' bucket_id: type: - string - 'null' option: type: array items: $ref: '#/components/schemas/Option' filter_name: type: array items: type: string type: type: string enum: - multiple_filter_values ResultsConfigResponse: type: object properties: results_config: type: object description: Config for the results page example: desktop: title: text: TITLE is_active: true description: text: DESCRIPTION is_active: false response_summary: text: SUMMARY is_active: true items_separator: ',' last_separator: AND quiz_version_id: type: string description: Version id of this quiz example: 11db5ac7-67e1-4000-9000-414d8425cab3 quiz_id: type: string description: id of quiz example: 11db5ac7-67e1-4000-9000-414d8425cab3 metadata: type: object description: Metadata for the quiz example: null CoverPageQuestion: type: object properties: id: type: number title: type: string example: TITLE description: type: - string - 'null' example: DESCRIPTION images: type: - object - 'null' allOf: - $ref: '#/components/schemas/Images' cta_text: type: - string - 'null' key: type: string is_skippable: type: boolean priority: type: - number - 'null' bucket_id: type: - string - 'null' type: type: string enum: - cover SingleFilterSelectQuestion: type: object properties: id: type: number title: type: string example: TITLE description: type: - string - 'null' example: DESCRIPTION images: type: - object - 'null' allOf: - $ref: '#/components/schemas/Images' cta_text: type: - string - 'null' key: type: string is_skippable: type: boolean priority: type: - number - 'null' bucket_id: type: - string - 'null' option: type: array items: $ref: '#/components/schemas/Option' filter_name: type: array items: type: string type: type: string enum: - single_filter_value Results: type: object properties: filter_expression: type: - object - 'null' description: Resulting filter expression generated from the various attributes selected after answering a quiz. example: or: - and: - name: TEST_FILTER_NAME value: TEST_FILTER_VALUE - not: name: TEST_FILTER_NAME_2 value: TEST_FILTER_VALUE_2 - name: TEST_FILTER_NAME_3 value: TEST_FILTER_VALUE_3 results: description: Final results type: - array - 'null' items: type: object NextQuestion: type: object properties: next_question: type: - object - 'null' description: Next question oneOf: - $ref: '#/components/schemas/MultipleSelectQuestion' - $ref: '#/components/schemas/SingleSelectQuestion' - $ref: '#/components/schemas/OpenTextQuestion' - $ref: '#/components/schemas/CoverPageQuestion' - $ref: '#/components/schemas/MultipleFilterSelectQuestion' - $ref: '#/components/schemas/SingleFilterSelectQuestion' total_questions: type: number description: Gives the total number of questions in the quiz version_id: type: string description: Version id of this quiz example: 11db5ac7-67e1-4000-9000-414d8425cab3 quiz_version_id: type: string description: Version id of this quiz example: 11db5ac7-67e1-4000-9000-414d8425cab3 quiz_id: type: string description: id of quiz example: 11db5ac7-67e1-4000-9000-414d8425cab3 quiz_session_id: type: string description: Session id of this quiz example: 11db5ac7-67e1-4000-9000-414d8425cab3 OpenTextQuestion: type: object properties: id: type: number title: type: string example: TITLE description: type: - string - 'null' example: DESCRIPTION images: type: - object - 'null' allOf: - $ref: '#/components/schemas/Images' cta_text: type: - string - 'null' key: type: string is_skippable: type: boolean priority: type: - number - 'null' bucket_id: type: - string - 'null' type: type: string enum: - open input_placeholder: type: - string - 'null' Images: type: object properties: primary_url: type: - string - 'null' example: PRIMARY_ASSET_URL primary_alt: type: - string - 'null' description: Alt string used for the primary url asset. example: PRIMARY_ASSET_ALT secondary_url: type: - string - 'null' example: SECONDARY_ASSET_URL secondary_alt: type: - string - 'null' description: Alt string used for the secondary url asset. example: SECONDARY_ASSET_ALT SingleSelectQuestion: type: object properties: id: type: number title: type: string example: TITLE description: type: - string - 'null' example: DESCRIPTION images: type: - object - 'null' allOf: - $ref: '#/components/schemas/Images' cta_text: type: - string - 'null' key: type: string is_skippable: type: boolean priority: type: - number - 'null' bucket_id: type: - string - 'null' option: type: array items: $ref: '#/components/schemas/Option' type: type: string enum: - single x-refined-from: - constructorio-ai-shopping-agent-openapi.yml - constructorio-quizzes-openapi.yml x-readme: explorer-enabled: false