> ## Documentation Index
> Fetch the complete documentation index at: https://docs.topsort.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```text theme={null}
POST /topsort_prompts/chat
```

### Headers

```http theme={null}
X-API-Key: YOUR_API_KEY
Content-Type: application/json
```

### Request Example

```json theme={null}
{
  "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

```json theme={null}
{
  "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:

```jsonl theme={null}
{"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

```text theme={null}
URL: https://mcp-server.api.topsort.ai/mcp
Transport: Streamable HTTP
```

```http theme={null}
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:

```json theme={null}
{
  "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

```bash theme={null}
curl https://your-api.example.com/catalog/health
```

```json theme={null}
{"status":"healthy","service":"catalog-agent-api"}
```