> ## Documentation Index
> Fetch the complete documentation index at: https://docs.alana.shopping/llms.txt
> Use this file to discover all available pages before exploring further.

# Browse

> Browse products by category without a text query

## Authentication

All requests must include an API key via the `x-api-key` header or `key` query parameter.

```bash theme={null}
curl -X POST https://alana.shopping/api/v1/browse \
  -H "Content-Type: application/json" \
  -H "x-api-key: ak_your_api_key" \
  -d '{"categoryPath": "roupas/camisetas"}'
```

## Rate Limits

| Level            | Limit          | Window   |
| ---------------- | -------------- | -------- |
| Per API key      | 1,000 requests | 1 minute |
| Per API key + IP | 100 requests   | 1 minute |

## Overview

Browse is designed for category pages — it returns products without a text query. Unlike search, which ranks by semantic similarity, browse ranks by `optimization_score` (the AI Commerce Score) by default.

Boost rules are automatically applied to browse results when active rules exist for the workspace.

## Request Format

All fields are optional. An empty body `{}` returns all products sorted by optimization score.

```json theme={null}
{
  "categoryPath": "roupas/camisetas",
  "sortBy": "price_asc",
  "page": 0,
  "hitsPerPage": 20
}
```

| Field          | Type            | Default              | Description                                                                        |
| -------------- | --------------- | -------------------- | ---------------------------------------------------------------------------------- |
| `categoryPath` | string or array | —                    | Category path to filter by (e.g. `"roupas/camisetas"` or `["roupas","camisetas"]`) |
| `sortBy`       | string          | `optimization_score` | Sort order (see Sorting below)                                                     |
| `page`         | integer         | `0`                  | 0-based page number                                                                |
| `hitsPerPage`  | integer (1–100) | `20`                 | Results per page                                                                   |
| `facets`       | string\[]       | —                    | Facet attributes to compute counts for                                             |
| `facetFilters` | array           | —                    | Disjunctive facet filters                                                          |

## Sorting

| Value                          | Description                       |
| ------------------------------ | --------------------------------- |
| `optimization_score` (default) | AI Commerce Score ranking         |
| `price_asc`                    | Price low to high                 |
| `price_desc`                   | Price high to low                 |
| `newest`                       | Most recently added               |
| `relevance`                    | Semantic similarity (embed-based) |

## Response Format

Browse returns the same Algolia-compatible response format as Search.

```json theme={null}
{
  "hits": [...],
  "nbHits": 142,
  "page": 0,
  "nbPages": 8,
  "hitsPerPage": 20,
  "facets": {
    "brand": {"Nike": 45, "Adidas": 32}
  },
  "processingTimeMs": 18
}
```