Detailed docs for the contextual search endpoint
The /search endpoint is the primary way to retrieve contextual product recommendations for your AI agent. It uses advanced semantic search to find products that match the user's intent.
POST /search
The request body must be a JSON object with the following properties:
| Parameter | Type | Description |
|---|---|---|
query | string | The natural language context or user query. Do not include PII. |
| Parameter | Type | Default | Description |
|---|---|---|---|
limit | integer | 3 | Maximum number of results to return (max 10). |
stream | boolean | false | If true, returns a Server-Sent Events (SSE) stream. |
filters | object | null | A set of hard constraints to apply to the results. |
sort | string | "relevance" | Sort order: relevance, price_asc, price_desc. |
min_relevance_score | float | 0.5 | Minimum relevance threshold (0.0 to 1.0). |
session_id | uuid | null | Optional identifier to maintain conversation context. |
conversation_context | array | null | History of the conversation for better matching. |
exclude_product_ids | array | null | List of product IDs to exclude from results. |
The filters object supports the following properties:
| Property | Type | Description |
|---|---|---|
min_price | float | Minimum price in USD. |
max_price | float | Maximum price in USD. |
merchant | string | Filter by specific retailer name. |
brand | string | Filter by product brand. |
category | string | Filter by product category. |
keyword_filter | string | Strict keyword match within the semantic results. |
Returns a JSON object (or SSE stream) containing:
| Property | Type | Description |
|---|---|---|
request_id | uuid | Unique identifier for this request. |
results | array | List of AdResponse objects. |
metadata | object | Search metadata including total_matches and session_id. |
| Property | Type | Description |
|---|---|---|
product_id | uuid | Permanent identifier for the product. |
impression_id | uuid | Unique identifier for this specific impression (for tracking). |
title | string | Product name. |
description | string | Product description. |
url | string | The destination URL for the product. |
price | string | Formatted price string (e.g., "$348.00"). |
merchant | string | Name of the retailer. |
brand | string | Brand name. |
relevance_score | float | Normalized relevance score (0.0 to 1.0). |
relevance_explanation | string | Human-readable explanation for the recommendation. |
image_url | string | URL for the product image. |
disclosure_text | string | Required affiliate disclosure text. |
curl -X POST https://api.vkra.org/search \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "gaming headphones",
"filters": {
"min_price": 100,
"max_price": 300
}
}'curl -X POST https://api.vkra.org/search \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "What about something wireless?",
"session_id": "550e8400-e29b-41d4-a716-446655440000",
"conversation_context": [
{"role": "user", "content": "I need gaming headphones"},
{"role": "assistant", "content": "Here are some top-rated wired options..."}
]
}'For processing multiple intents in one request, use the /search/batch endpoint.
POST /search/batch
{
"queries": [
{ "query": "running shoes", "limit": 1 },
{ "query": "fitness tracker", "limit": 1 }
]
}