Skill: gzipped/browse-products (version 1.0.0)

--- name: products-browse-skill description: 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](reference.md) 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](reference.md). ## cURL Examples ### Single search ```bash curl -G "https://pbs-search-api-fp45p.ondigitalocean.app/api/v1/products/search" \ -d [REDACTED_SECRET] \ -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 } } ]'


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)