Agent insights

Retrieve search bar AI overviews

Produce the AI overview for a shopper's search query: a short written summary of what the catalog offers for it, and the handful of products that answer it best. This is the search bar experience, so the result is deliberately compact (one set of four or five products, or several sets of a single product, each set introduced by a line of prose), small enough to sit above the traditional search results and pointed enough to draw the shopper into a full chat conversation. Not every query suits that treatment, and the index key's search bar configuration decides: a query its classification judges better served by traditional search is answered with 422 before any content is produced, and the caller renders its own search results instead. A configuration without query classification answers every query. shopper_input is the query itself. search takes no parameters, because it always runs the searchbar domain configured for the index key, and a key without that domain is answered with 400. Leave num_result_events unset unless dropping product sets is the intent: the agent chooses between one multi-product set and several single-product sets, so a cap of 1 keeps one product while the prose around it still describes the rest. Results stream back as server-sent events (text/event-stream) so the overview can be rendered as it is produced. To receive the finished overview as a single JSON document instead, send Accept: application/json.

post/v1/agent_insights/search

Request

  • Base URL
    https://agent.cnstrc.com
  • URL
    https://agent.cnstrc.com/v1/agent_insights/search
  • Auth
    none required

Query parameters

keystring required

The key of the index to use.

thread_idstring uuid

A unique identifier for the conversation thread. This ID links multiple requests to the same conversation. When omitted, a new thread is created.

guardboolean

Turn the content moderation check on or off. When on, shopper input is screened before the agent processes it.

num_result_eventsinteger

The maximum number of result events to return.

num_results_per_eventinteger

The maximum number of results to return per item_results event.

fieldsstring[]

A list of specific item fields to return in the response. Allows the request to control which fields are returned.

show_hidden_fieldsboolean

A flag to return all hidden fields in the response.

hidden_fieldsstring[]

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'default' | 'all' | 'matched'
groups_max_depthinteger

The maximum depth of the group hierarchy in the response.

groups_startstring

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.

groups_pathstring[]

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'relevance' | 'value' | 'num_matches'
groups_sort_order'ascending' | 'descending'
show_hidden_facetsboolean

A flag to return all facets configured as hidden in response.facets.

hidden_facetsstring[]

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_optionsboolean

A flag to return all hidden facets options in the response.

show_protected_facetsboolean

A flag to return all protected facets in the response. Requires authentication.

facet_optionsobject

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_limitinteger

The maximum limit of the facet groups returned in the response.

show_hidden_sort_optionsboolean

A flag to return all sort options configured as hidden in response.sort_options.

hidden_sort_optionsstring[]

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.

An object containing options to format different aspects of the response.

qsstring json

Additional query parameters to forward to the underlying Constructor search, browse and recommendations API calls, as a JSON-encoded string: for example qs={"sort_by":"price","sort_order":"ascending"}. Each mode forwards only the keys that apply to the calls it makes, and any key managed by page_context.filters must not be overridden here.

cstring

The ID of the client and version that the request is coming from, such as cio-js-2.90.

usstring[]

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.

uistring

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.

feature_variantsobject

Feature variants keyed by feature name. Accepts flattened feature_variants[<feature_name>] query parameters.

featuresobject

Feature toggles keyed by feature name. Accepts flattened features[<feature_name>] query parameters.

sinteger

An integer representing the user's session number (starting with 1), incremented after a 30 minute period of inactivity.

istring

A globally unique identifier for the user browser (or mobile application instance) making the request.

Request body

shopper_inputstring required

The shopper's search query.

parametersSearchParameters

Extra parameters for POST /v1/agent_insights/search. The query is carried by shopper_input, and the domain is always the index key's searchbar domain rather than a choice.

Response

AI-powered agent insights, streamed as server-sent events or aggregated into a single JSON document.

result_idstring required

Agent insight result ID.

thread_idstring uuid

A unique identifier for the conversation thread. Pass it back on the next request to continue the same conversation. Only populated for conversational modes.

status'complete' | 'partial' required

Whether the collected stream represents the agent's full answer.

  • complete: the underlying stream finished normally.
  • partial: the stream was truncated or emitted a server_error, so the answer may be incomplete.
messagestring

The agent's text output. When the agent produced several message events they are joined in the order they were emitted.

route'customer_support'

Where the client should send the shopper next. customer_support marks a customer support answer.

Example response

{
  "follow_up_refinement": {
    "options": [
      "Yes, sub-zero",
      "No, mild weather"
    ],
    "question": "Do you need it for winter conditions?"
  },
  "item_results": [
    {
      "request": {
        "ids": [
          "item_id_1"
        ],
        "params": {
          "num_results_per_page": 20
        },
        "type": "browse"
      },
      "response": {
        "results": [
          {
            "value": "Waterproof Hiking Boot",
            "matched_terms": [
              "waterproof",
              "hiking"
            ],
            "is_slotted": false,
            "labels": {},
            "data": {
              "id": "item_id_1",
              "url": "https://example.com/product/item_id_1",
              "image_url": "https://cdn.example.com/item_id_1.jpg"
            }
          }
        ]
      },
      "result_id": "973e152a-ee03-47d2-a01b-1214da90a02b"
    }
  ],
  "message": "Based on your interest in hiking gear, here are some waterproof options...",
  "result_id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "complete",
  "thread_id": "662e8400-e29b-41d4-a716-446655440001"
}

Changes

No recorded changes to this operation across all 1 revision of this API.