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#

text

GET https://pbs-search-api-fp45p.ondigitalocean.app/api/v1/products/search?query=<your-query>

Example:

text

GET https://pbs-search-api-fp45p.ondigitalocean.app/api/v1/products/search?query=wireless+bluetooth+headphones

2. Filter by Price Range#

text

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#

ParameterRequiredDefaultDescriptionqueryYes—Natural language search text (max 500 chars)minPriceNo—Minimum price filtermaxPriceNo—Maximum price filterpageNo1Page number (1-based)pageSizeNo20Results per page (max 100)titleOnlyNofalseSearch only product titlesdescriptionOnlyNofalseSearch only product descriptionssortByNorelevanceSort: relevance, price, date``sortOrderNodescOrder: asc, desc

Bulk Search#

For multiple queries in one request:

text

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#

bash

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#

bash

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 }
    }
  ]'