Product Search
Note
This endpoint is publicly accessible — no authentication required.
Endpoint
GET /products
Parameters
| Parameter |
Type |
Required |
Description |
| q |
string |
yes |
Search query |
| category |
string |
no |
Filter by category (see Categories below) |
| min_price |
number |
no |
Minimum price in USD |
| max_price |
number |
no |
Maximum price in USD |
| brand |
string |
no |
Filter by brand name (exact match) |
| in_stock |
bool |
no |
Only show in-stock items (default: false) |
| sort |
string |
no |
Sort by: relevance, price_asc, price_desc, rating, newest |
| page |
number |
no |
Page number (default: 1) |
| per_page |
number |
no |
Results per page, max 50 (default: 20) |
Categories
Valid category values:
audio — Headphones, speakers, microphonescomputers — Laptops, desktops, monitorsphones — Smartphones, cases, chargersgaming — Consoles, controllers, accessoriescameras — Cameras, lenses, tripodssmart-home — Smart speakers, lights, thermostatswearables — Smartwatches, fitness trackers
Example
Request:
GET /products?q=wireless+headphones&sort=rating&max_price=100&in_stock=true
Response (200 OK):
{
"products": [
{
"id": "prod_8x7k",
"name": "SoundWave Pro Wireless Headphones",
"brand": "SoundWave",
"price": 79.99,
"category": "audio",
"rating": 4.7,
"review_count": 1243,
"in_stock": true,
"image_url": "https://bobs-store.com/images/prod_8x7k.jpg",
"url": "https://bobs-store.com/products/prod_8x7k"
},
{
"id": "prod_m3nq",
"name": "BassX Foldable Bluetooth Headphones",
"brand": "BassX",
"price": 49.99,
"category": "audio",
"rating": 4.3,
"review_count": 876,
"in_stock": true,
"image_url": "https://bobs-store.com/images/prod_m3nq.jpg",
"url": "https://bobs-store.com/products/prod_m3nq"
}
],
"total": 42,
"page": 1,
"per_page": 20
}
Error Handling
| Code |
Meaning |
Action |
| 400 |
Invalid parameters |
Check parameter types and values |
| 429 |
Rate limited |
Wait, retry after Retry-After header |
| 500 |
Server error |
Retry with exponential backoff |
Notes
- Search is case-insensitive and supports partial matching.
- Empty
q with a category filter returns top products in that category.
- Results are deduplicated — the same product won't appear twice.
- Pagination: use
page and per_page. The response total field shows total matches.
1---2name: search3description: Search and browse products in Bob's Online Store catalog. Use when the user wants to find products by keyword, category, price range, or brand. Returns structured product data including prices, ratings, and stock availability. Supports pagination and sorting. Do NOT use for order management or account operations.4---56# Product Search78## Note910This endpoint is publicly accessible — no authentication required.1112## Endpoint1314GET /products1516## Parameters1718| Parameter | Type | Required | Description |19|------------|--------|----------|------------------------------------------|20| q | string | yes | Search query |21| category | string | no | Filter by category (see Categories below)|22| min_price | number | no | Minimum price in USD |23| max_price | number | no | Maximum price in USD |24| brand | string | no | Filter by brand name (exact match) |25| in_stock | bool | no | Only show in-stock items (default: false)|26| sort | string | no | Sort by: `relevance`, `price_asc`, `price_desc`, `rating`, `newest` |27| page | number | no | Page number (default: 1) |28| per_page | number | no | Results per page, max 50 (default: 20) |2930## Categories3132Valid category values:3334- `audio` — Headphones, speakers, microphones35- `computers` — Laptops, desktops, monitors36- `phones` — Smartphones, cases, chargers37- `gaming` — Consoles, controllers, accessories38- `cameras` — Cameras, lenses, tripods39- `smart-home` — Smart speakers, lights, thermostats40- `wearables` — Smartwatches, fitness trackers4142## Example4344Request:4546```47GET /products?q=wireless+headphones&sort=rating&max_price=100&in_stock=true48```4950Response (200 OK):5152```json53{54 "products": [55 {56 "id": "prod_8x7k",57 "name": "SoundWave Pro Wireless Headphones",58 "brand": "SoundWave",59 "price": 79.99,60 "category": "audio",61 "rating": 4.7,62 "review_count": 1243,63 "in_stock": true,64 "image_url": "https://bobs-store.com/images/prod_8x7k.jpg",65 "url": "https://bobs-store.com/products/prod_8x7k"66 },67 {68 "id": "prod_m3nq",69 "name": "BassX Foldable Bluetooth Headphones",70 "brand": "BassX",71 "price": 49.99,72 "category": "audio",73 "rating": 4.3,74 "review_count": 876,75 "in_stock": true,76 "image_url": "https://bobs-store.com/images/prod_m3nq.jpg",77 "url": "https://bobs-store.com/products/prod_m3nq"78 }79 ],80 "total": 42,81 "page": 1,82 "per_page": 2083}84```8586## Error Handling8788| Code | Meaning | Action |89|------|---------------------|-------------------------------------|90| 400 | Invalid parameters | Check parameter types and values |91| 429 | Rate limited | Wait, retry after `Retry-After` header |92| 500 | Server error | Retry with exponential backoff |9394## Notes9596- Search is case-insensitive and supports partial matching.97- Empty `q` with a `category` filter returns top products in that category.98- Results are deduplicated — the same product won't appear twice.99- Pagination: use `page` and `per_page`. The response `total` field shows total matches.
0xtresser