Skip to main content

​
Integration Options

Use either of the following:
  • Agent API: best for chat interfaces and multi-turn conversational search
  • MCP Server: best for custom integrations and direct tool access

​
Option 1: Agent API

The Agent API provides a conversational search experience with memory across sessions.

​
Endpoint

POST /catalog/search

​
Headers

X-API-Key: YOUR_API_KEY
Content-Type: application/json

​
Request Example

{
  "query": "I need running shoes under $150",
  "session_id": "user-session-123",
  "max_results": 10,
  "max_sponsored": 3,
  "streaming": false
}
Key fields:
  • query (required): natural language query
  • session_id (optional): conversation continuity
  • user_id (optional): user identifier
  • max_results (optional, default 5): total products
  • max_sponsored (optional, default 2): sponsored products
  • streaming (optional, default false): NDJSON streaming mode

​
Response Example

{
  "text": "I found some great running shoes for you!",
  "session_id": "user-session-123",
  "data": {
    "products": [
      {
        "id": "prod-123",
        "name": "Nike Air Zoom Pegasus 40",
        "price": 129.99,
        "is_sponsored": true,
        "resolvedBidId": "bid-456"
      },
      {
        "id": "prod-456",
        "name": "Adidas Ultraboost 22",
        "price": 139.99,
        "is_sponsored": false
      }
    ],
    "summary": {
      "total_results": 10,
      "sponsored_results": 1,
      "organic_results": 9
    }
  }
}

​
Streaming Mode

Set streaming: true to receive NDJSON events: 
{"event":"start","session_id":"user-session-123"}
{"event":"text_chunk","content":"I found some "}
{"event":"text_chunk","content":"great running shoes!"}
{"event":"done","session_id":"user-session-123","data":{}}

​
Multi-turn Sessions

Reuse the same session_id for follow-up queries to preserve context.

​
Option 2: MCP Server

If you are building your own agent, connect directly to the MCP server and call search_products.

​
Connection

URL: https://your-mcp-server.example.com/mcp
Transport: Streamable HTTP

X-API-Key: YOUR_API_KEY

​
Tool: search_products

Main parameters:
  • query (required): natural language query
  • marketplace_id (optional): marketplace UUID
  • max_results (optional, default 5)
  • max_sponsored (optional, default 2)
  • price_filtering (optional, default false)
  • min_price and max_price (optional, if filtering enabled)
Example call payload: 
{
  "query": "running shoes under $150",
  "max_results": 10,
  "max_sponsored": 3
}

​
Product Response Fields

  • id: product identifier
  • name: product name
  • brand: brand name
  • price: numeric price
  • currency: currency code (for example USD)
  • categories: category list
  • image_url: product image URL
  • similarity_score: semantic relevance score
  • rank: result position
  • is_sponsored: sponsored flag
  • description: product description
  • availability: stock status
  • resolvedBidId: sponsored bid ID for attribution

​
Best Practices

  • Treat is_sponsored: true as paid placement
  • Track resolvedBidId for attribution and analytics
  • Clearly label sponsored placements in UI

​
Session Management

  • Generate a unique session_id per conversation
  • Reuse session IDs across follow-up turns
  • Start a new session for a new conversation

​
Error Handling

  • Use generous timeouts (60-180 seconds) for complex queries
  • Retry transient 5xx errors with exponential backoff
  • In streaming mode, handle error events gracefully

​
Health Check

curl https://your-api.example.com/catalog/health

{"status":"healthy","service":"catalog-agent-api"}