# Search products

Search returns ranked product cards across every brand. It is the fastest way to turn a shopper's intent into products.

```bash
curl "https://dev.ziffi.xyz/v1/search?q=gentle+serum+for+oily+skin&limit=5"
```

## Modes

Pick how the query is matched with `mode`.

| Mode | Best for |
|---|---|
| `hybrid` (default) | General relevance. Blends keyword and meaning. |
| `semantic` | Intent and description, for example "something to remove dark circles". |
| `lexical` | Exact tokens, for example a brand or a specific name. |

```bash
curl "https://dev.ziffi.xyz/v1/search?q=water+resistant+headphones&mode=semantic&limit=5"
```

## Filters and sort

| Param | Meaning |
|---|---|
| `price_min`, `price_max` | Price bounds, in minor units. |
| `in_stock` | `true` to keep only buyable products. |
| `on_sale` | `true` to keep only discounted products. |
| `brand` | Restrict to one brand slug. |
| `facets` | A JSON object of exact filters, for example `{"color":"navy"}`. |
| `sort` | `relevance`, `price_asc`, `price_desc`, `rating`, `newest`. |
| `limit`, `cursor` | Page size and the opaque cursor. |

```bash
curl "https://dev.ziffi.xyz/v1/search?q=serum&price_max=50000&in_stock=true&sort=rating"
```

## The response

```json
{
  "data": [
    { "id": "…", "product_uid": "sha:…", "title": "Black Seed Hair Serum",
      "brand": "The Natural Wash", "brand_slug": "the-natural-wash",
      "price_min_minor": 39900, "compare_at_minor": 59900, "discount_pct": 33,
      "currency": "INR", "in_stock": true, "rating": 4.6, "image": "https://…" }
  ],
  "tier": "graph",
  "provenance": { "engine": "hybrid" }
}
```

## Next steps

- [Get a product](#/product): full detail for a card.
- [Pagination](#/pagination): page through results.
- [Build an AI agent](#/agents): the same search over MCP.