Agentic Search API Specification

Overview

The Agentic Search API facilitates deep, intent-focused search patterns. A user’s query is comprehended by a generative AI agent, which designs a set of search queries around it. The agent retrieves items from a Marqo index and returns a collection of result categories. Clients can then render these categories and offer relevant options to the user.

The API supports both streaming and non-streaming modes. Streaming provides real-time feedback to the user. Developers can override features like the number of results per category, max number of categories, agent parameters, and search settings.

Use Cases

This API is ideal for situations where a user’s query could span multiple, potentially non-overlapping product categories. The system interprets a high-level query and generates sub-queries ("head queries") that organize results by category.

Best suited for:

Marqo users with diverse product catalogs
Applications handling ambiguous or broad user queries

API Endpoint

Paths

Streaming: GET /indexes/{index_name}/agentic-search/stream
Non-streaming: POST /indexes/{index_name}/agentic-search

Supported HTTP Methods

GET (for streaming)
POST (for non-streaming)

Authentication

API key or token-based authentication

Request Format

Streaming: Use GET with URL query parameters due to SSE constraints.
Non-streaming: Use POST with parameters in the request body.

Agentic Search Parameters

Parameter	Type	Default	Description
`q`	String	(required)	The user’s query
`agenticSearchLimit`	Integer	`12`	Number of results per category (distinct from `searchSettings.limit`)
`maxCategories`	Integer	`5`	Maximum number of categories the agent will attempt to return
`clickableSummary`	Boolean	`true`	Defines if the summary will contain markdown content for interaction
`searchSettings`	Dict	see below	Configuration used during search (see below)

Clickable Summary

The agent will incorporate suggested follow-up queries in its summary. If this is set to true, the agent will implant this pattern in the summary: [[button:query=<your_query>]]. Custom markdown renderers can then display that text as a button or other element.

Search Settings

Parameter	Type	Default	Description
`limit`	Integer	`10`	Maximum number of products to return
`offset`	Integer	`0`	Number of products to skip (for pagination)
`filter`	String	`null`	Filter string using Marqo's query DSL to narrow search results
`attributesToRetrieve`	List[String]	`["productTitle", "variantTitle", "price", "variantImageUrl", "collections", "_id", "_score"]`	Specific product fields to return. If not specified, returns the default core product fields
`facets`	Dict	`null`	Facet configuration for aggregated results
`sortBy`	Dict	`null`	Sort configuration for results ordering
`userId`	String	`null`	User ID for personalization
`sessionId`	String	`null`	Session ID for personalization

Example Requests

1. Non-Streaming POST Request (with updated `searchSettings`)

POST /indexes/my-first-index/agentic-search HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "q": "I need something to wear to a wedding",
  "sessionId": "session-abc123",
  "userId": "user-456",
  "agenticSearchLimit": 10,
  "maxCategories": 4,
  "clickableSummary": true,
  "searchSettings": {
    "limit": 24,
    "offset": 0,
    "filter": "availability:true",
    "attributesToRetrieve": [
      "productTitle",
      "variantTitle",
      "price",
      "variantImageUrl",
      "collections",
      "_id",
      "_score"
    ],
    "facets": null,
    "sortBy": null,
    "userId": "user-456",
    "sessionId": "session-abc123"
  }
}

2. Streaming GET Request with Base64-Encoded Query Parameters (SSE)

Step 1: Compose JSON payload (pretty-printed here for readability)

{
  "q": "I need something to wear to a wedding",
  "sessionId": "session-abc123",
  "userId": "user-456",
  "agenticSearchLimit": 10,
  "maxCategories": 4,
  "clickableSummary": true,
  "searchSettings": {
    "limit": 24,
    "offset": 0,
    "filter": "availability:true",
    "attributesToRetrieve": [
      "productTitle",
      "variantTitle",
      "price",
      "variantImageUrl",
      "collections",
      "_id",
      "_score"
    ],
    "facets": null,
    "sortBy": null,
    "userId": "user-456",
    "sessionId": "session-abc123"
  }
}

Step 2: Base64 encode this JSON (URL-safe, no padding)

eyJxIjogIkkgbmVlZCBzb21ldGhpbmcgdG8gd2VhciB0byBhIHdlZGRpbmciLCAic2Vzc2lvbklk\nIjogInNlc3Npb24tYWJjMTIzIiwgInVzZXJJZCI6ICJ1c2VyLTQ1NiIsICJhZ2VudGljU2VhcmNo\nTGltaXQiOiAxMCwgIm1heENhdGVnb3JpZXMiOiA0LCAiY2xpY2thYmxlU3VtbWFyeSI6IHRydWUs\nICJzZWFyY2hTZXR0aW5ncyI6IHsibGltaXQiOiAxMCwgIm9mZnNldCI6IDAsICJmaWx0ZXIiOiAi\nYXZhaWxhYmlsaXR5OnRydWUiLCAiYXR0cmlidXRlc1RvUmV0cmlldmUiOiBbInByb2R1Y3RUaXRs\nZSIsICJ2YXJpYW50VGl0bGUiLCAicHJpY2UiLCAidmFyaWFudEltYWdlVXJsIiwgImNvbGxlY3Rp\nb25zIiwgIl9pZCIsICJfc2NvcmUiXSwgImZhY2V0cyI6IG51bGwsICJzb3J0QnkiOiBudWxsLCAi\ndXNlcklkIjogInVzZXItNDU2IiwgInNlc3Npb25JZCI6ICJzZXNzaW9uLWFiYzEyMyJ9fQ==\n

Step 3: Use in the URL query param `payload`

GET /indexes/my-first-index/agentic-search/stream?payload=eyJxIjogIkkgbmVlZCBzb21ldGhpbmcgdG8gd2VhciB0byBhIHdlZGRpbmciLCAic2Vzc2lvbklk\nIjogInNlc3Npb24tYWJjMTIzIiwgInVzZXJJZCI6ICJ1c2VyLTQ1NiIsICJhZ2VudGljU2VhcmNo\nTGltaXQiOiAxMCwgIm1heENhdGVnb3JpZXMiOiA0LCAiY2xpY2thYmxlU3VtbWFyeSI6IHRydWUs\nICJzZWFyY2hTZXR0aW5ncyI6IHsibGltaXQiOiAxMCwgIm9mZnNldCI6IDAsICJmaWx0ZXIiOiAi\nYXZhaWxhYmlsaXR5OnRydWUiLCAiYXR0cmlidXRlc1RvUmV0cmlldmUiOiBbInByb2R1Y3RUaXRs\nZSIsICJ2YXJpYW50VGl0bGUiLCAicHJpY2UiLCAidmFyaWFudEltYWdlVXJsIiwgImNvbGxlY3Rp\nb25zIiwgIl9pZCIsICJfc2NvcmUiXSwgImZhY2V0cyI6IG51bGwsICJzb3J0QnkiOiBudWxsLCAi\ndXNlcklkIjogInVzZXItNDU2IiwgInNlc3Npb25JZCI6ICJzZXNzaW9uLWFiYzEyMyJ9fQ==\n HTTP/1.1
Host: api.example.com
Accept: text/event-stream
Authorization: Bearer YOUR_API_KEY

Response

JSON Response Structure

Field	Type	Description
`summary`	String	AI-generated summary of the category results (may include links/buttons)
`categoryHits`	List	List of result categories and associated items (see below)
`hits`	List	Non-agentic search results using the provided query
`facets`	Dict	Optional facets metadata (if configured)
`redirect`	Dict	Optional redirect (see below)

`categoryHits` Structure

Field	Type	Description
`category`	String	The category label
`hits`	List	Documents returned for this category query

`redirect` Structure

Field	Type	Description
`reason`	String	Reason for redirect
`url`	String	URL to redirect the user to

Streaming Response

Delivered via Server-Sent Events (SSE).
Each event sends the entire current snapshot of the full response schema.
Snapshots should be treated as stateful replacements, not deltas.
The final event is of type stream-end indicate the end of the stream

Example Stream Output

event: message
data: {
  "summary": "Here are some options you might like for party wear.",
  "categoryResults": [
    {
      "category": "Dresses",
      "hits": [
        {"_id": "dress_001", "title": "Red Sequin Dress", "price": 89.99},
        {"_id": "dress_002", "title": "Black Silk Gown", "price": 129.99}
      ]
    }
  ]
}

event: message
data: {
  "summary": "Here are some options you might like for party wear. Try searching for [[button:query=Casual party outfits]], [[button:query=Formal party attire]] or [[button:query=Accessories for a party]] for more options.",
  "categoryResults": [
    {
      "category": "Dresses",
      "hits": [
        {"_id": "dress_001", "title": "Red Sequin Dress", "price": 89.99},
        {"_id": "dress_002", "title": "Black Silk Gown", "price": 129.99},
        {"_id": "dress_003", "title": "Blue Off-Shoulder Dress", "price": 99.99}
      ]
    },
    {
      "category": "Shoes",
      "hits": [
        {"_id": "shoe_001", "title": "Silver Heels", "price": 59.99},
        {"_id": "shoe_002", "title": "Strappy Sandals", "price": 49.99}
      ]
    }
  ]
}

event: stream-end
data: {}