browse-products

Semantic product search API using vector embeddings. Search products by natural language queries with price filtering, pagination, and relevance scoring. Use when the user wants to search products, browse a product catalog, or find items by description.

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

1. Write natural queries — Semantic search works best with descriptive phrases (e.g. "comfortable running shoes for marathon" vs "shoes marathon")
2. Use price filters — Combine minPrice and maxPrice to narrow results
3. Use titleOnly for precision — When searching for specific product names
4. Check relevanceScore — Scores closer to 1.0 indicate stronger semantic matches
5. 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:

1. 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.
2. 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).
3. 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.
4. 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.
5. 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 model
• results[] — 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 }
    }
  ]'