Quick Start
Make your first contextual search request with VKRA in minutes
Quick Start Guide
This guide will help you integrate VKRA and make your first contextual product search.
Prerequisites
- An VKRA account.
- An API key (available in your dashboard).
- A basic understanding of REST APIs.
1. Get Your API Key
- Log in to the VKRA Dashboard.
- Navigate to API Keys.
- Create a new key and copy the full key. Keep it secure!
2. Make Your First Search Request
Send a natural language query to the /search endpoint to find relevant products.
cURL Example
curl -X POST https://api.vkra.org/search \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "I need a high-quality microphone for recording podcasts",
"limit": 3
}'Python Example
import requests
url = "https://api.vkra.org/search"
headers = {
"x-api-key": "YOUR_API_KEY",
"Content-Type": "application/json"
}
payload = {
"query": "I need a high-quality microphone for recording podcasts",
"limit": 3
}
response = requests.post(url, json=payload, headers=headers)
data = response.json()
for result in data['results']:
print(f"Product: {result['title']}")
print(f"Price: {result['price']}")
print(f"URL: {result['url']}\n")JavaScript Example
const response = await fetch('https://api.vkra.org/search', {
method: 'POST',
headers: {
'x-api-key': 'YOUR_API_KEY',
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: 'I need a high-quality microphone for recording podcasts',
limit: 3
})
});
const data = await response.json();
console.log(data.results);3. Handle the Response
A successful response returns a SearchResponse object:
{
"request_id": "550e8400-e29b-41d4-a716-446655440000",
"results": [
{
"product_id": "product_123",
"impression_id": "imp_abc456",
"title": "Sony WH-1000XM5",
"price": "$348.00",
"url": "https://vkra.org/p/123",
"relevance_score": 0.98,
"relevance_explanation": "Matched because you mentioned noise-cancelling headphones."
}
],
"metadata": {
"total_matches": 15,
"session_id": "sess_789"
}
}4. Track Interactions (Optional but Recommended)
To ensure proper attribution and improve your agent's performance, track when a user clicks on a product:
curl -X POST https://api.vkra.org/clicks/imp_abc456 \
-H "x-api-key: YOUR_API_KEY"Next Steps
- Search Reference: Explore all search parameters like price filters, brands, and streaming.
- Best Practices: Learn about privacy-first integration and performance optimization.
- Frontend Examples: See how to build a product recommendation UI.