Setup and Integration

Set up Topsort Prompts and integrate with Agent API or MCP.

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 /topsort_prompts/chat

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://mcp-server.api.topsort.ai/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

Sponsored Products

• 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"}