> ## 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.

# Boost Rules

> Manage boost and bury rules to fine-tune product ranking

## Overview

Boost rules let you promote or demote products in search and browse results based on product attributes. Rules are applied post-ranking — only on results that already match the query.

* **Boost** (`boost > 0`): pushes matching products toward the top
* **Bury** (`boost < 0`): pushes matching products toward the bottom
* Rules are only applied when `sortBy` is `relevance` or `optimization_score`

## Authentication

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

```bash theme={null}
curl -H "x-api-key: ak_your_api_key" https://alana.shopping/api/v1/boost-rules
```

## Rate Limits

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

## List Boost Rules

```bash theme={null}
GET /api/v1/boost-rules
```

Returns all boost rules for the workspace.

```json theme={null}
{
  "rules": [
    {
      "id": "uuid",
      "name": "Boost Nike products",
      "condition": { "field": "brand", "value": "Nike" },
      "boost": 0.5,
      "active": true,
      "createdAt": "2026-03-13T00:00:00Z",
      "updatedAt": "2026-03-13T00:00:00Z"
    }
  ]
}
```

## Create Boost Rule

```bash theme={null}
POST /api/v1/boost-rules
Content-Type: application/json
```

```json theme={null}
{
  "name": "Boost in-stock products",
  "condition": { "field": "availability", "value": "in_stock" },
  "boost": 0.3,
  "active": true
}
```

Returns `201 Created` with the created rule.

### Condition Fields

| Field          | Example values                      |
| -------------- | ----------------------------------- |
| `brand`        | `"Nike"`, `"Adidas"`                |
| `availability` | `"in_stock"`, `"out_of_stock"`      |
| `color`        | `"blue"`, `"red"` (from attributes) |
| Any attribute  | Top-level or attribute field name   |

### Boost Range

| Value         | Effect                              |
| ------------- | ----------------------------------- |
| `1.0`         | Maximum boost — moves to very top   |
| `0.1`–`0.9`   | Moderate boost                      |
| `0`           | No effect                           |
| `-0.1`–`-0.9` | Moderate bury                       |
| `-1.0`        | Maximum bury — moves to very bottom |

## Update Boost Rule

```bash theme={null}
PUT /api/v1/boost-rules/{id}
Content-Type: application/json
```

Partial update — only provided fields are changed.

```json theme={null}
{ "boost": 0.8, "active": true }
```

Returns `200 OK` with the updated rule.

## Delete Boost Rule

```bash theme={null}
DELETE /api/v1/boost-rules/{id}
```

Returns `204 No Content`.