Products Browse Skill
This skill provides access to a semantic product search API that uses vector embeddings to find products by meaning rather than keyword matching.
Prerequisites
- Valid query text (natural language, max 500 characters)
Quick Start
1. Search for Products
GET https://pbs-search-api-fp45p.ondigitalocean.app/api/v1/products/search?query=<your-query>
Example:
GET https://pbs-search-api-fp45p.ondigitalocean.app/api/v1/products/search?query=wireless+bluetooth+headphones
2. Filter by Price Range
GET https://pbs-search-api-fp45p.ondigitalocean.app/api/v1/products/search?query=running+shoes&minPrice=50&maxPrice=200
3. Browse Full API Documentation
See complete API reference for all endpoints, parameters, and response formats.
Search Parameters
| Parameter | Required | Default | Description |
|---|
query | Yes | — | Natural language search text (max 500 chars) |
minPrice | No | — | Minimum price filter |
maxPrice | No | — | Maximum price filter |
page | No | 1 | Page number (1-based) |
pageSize | No | 20 | Results per page (max 100) |
titleOnly | No | false | Search only product titles |
descriptionOnly | No | false | Search only product descriptions |
sortBy | No | relevance | Sort: relevance, price, date |
sortOrder | No | desc | Order: asc, desc |
Bulk Search
For multiple queries in one request:
POST https://pbs-search-api-fp45p.ondigitalocean.app/api/v1/products/search/bulk
Send a JSON array of search requests (max 50 per request).
Best Practices
- Write natural queries — Semantic search works best with descriptive phrases (e.g. "comfortable running shoes for marathon" vs "shoes marathon")
- Use price filters — Combine
minPrice and maxPrice to narrow results
- Use
titleOnly for precision — When searching for specific product names
- Check
relevanceScore — Scores closer to 1.0 indicate stronger semantic matches
- Paginate wisely — Smaller pages (10-20) are faster than large ones
Displaying Products to the User
When presenting search results to the user, follow these guidelines to ensure a rich and useful experience:
- Show product images — Use the
imageUrls field from each product to display as many product photos as possible. Visual content is essential for helping users evaluate products.
- Always display the price — Show the
price field clearly. If priceWithoutDiscount and discountPercent are available, highlight the discount (e.g., strikethrough the original price, show the discount percentage).
- Include product links — Every product should have a clickable link (product title or a "View in Store" button) pointing to the product
url so the user can navigate directly to the store.
- Use a card-based layout — Present each product as a card containing: image(s), title, price, and a link to the store. This creates a clean, scannable browsing experience.
- Keep descriptions concise — Show a short product description or key attributes, but prioritize images and pricing for quick scanning.
Response Format
Each search returns:
metadata — pagination info, search time, cache status, embedding modelresults[] — matching products with id, title, description, price, url, relevanceScore, and attributes
For complete response schema, see API reference.
cURL Examples
Single search
curl -G "https://pbs-search-api-fp45p.ondigitalocean.app/api/v1/products/search" \
-d "query=wireless+bluetooth+headphones" \
-d "minPrice=50" \
-d "maxPrice=200" \
-d "page=1" \
-d "pageSize=10"
Bulk search
curl -X POST "https://pbs-search-api-fp45p.ondigitalocean.app/api/v1/products/search/bulk" \
-H "Content-Type: application/json" \
-d '[
{
"query": { "text": "running shoes" },
"pagination": { "page": 1, "pageSize": 5 }
},
{
"query": { "text": "tennis racket" },
"pagination": { "page": 1, "pageSize": 5 }
}
]'
