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

# Recommendations

> Get product recommendations using 8 different models

## Authentication

All requests must include an API key via the `x-api-key` header or `key` query parameter.
The workspace is resolved automatically from the API key — do not pass `workspaceId` in the request body.

```bash theme={null}
curl -X POST https://alana.shopping/api/v1/recommend \
  -H "Content-Type: application/json" \
  -H "x-api-key: ak_your_api_key" \
  -d '{
    "model": "similar",
    "productId": "550e8400-e29b-41d4-a716-446655440000",
    "limit": 10
  }'
```

## Recommendation Models

| Model                        | Type        | Required Params | Description                                                 |
| ---------------------------- | ----------- | --------------- | ----------------------------------------------------------- |
| `similar`                    | Catalog     | `productId`     | Products semantically similar to the given product          |
| `complementary`              | Catalog     | `productId`     | Products that complement (go well with) the given product   |
| `alternatives`               | Catalog     | `productId`     | Alternative products in the same category at similar price  |
| `match_profile`              | Catalog     | `productId`     | Products matching the same style/attribute profile          |
| `trending`                   | Catalog     | —               | Top trending products in the workspace catalog              |
| `frequently_bought_together` | Event-based | `productId`     | Products commonly purchased alongside the given product     |
| `recommended_for_you`        | Event-based | `userId`        | Personalized recommendations based on user behavior history |
| `buy_it_again`               | Event-based | `userId`        | Products the user has purchased before and may want again   |

## Graceful Degradation

Event-based models (`frequently_bought_together`, `recommended_for_you`, `buy_it_again`) require sufficient
event volume. When event data is insufficient, these models automatically fall back to a catalog-based model.
The response includes `fallback: true` and `fallbackModel` indicating which model was used instead.

## Request Format

```json theme={null}
{
  "model": "similar",
  "productId": "550e8400-e29b-41d4-a716-446655440000",
  "limit": 10
}
```

### Parameters

| Field       | Type    | Required    | Description                              |
| ----------- | ------- | ----------- | ---------------------------------------- |
| `model`     | string  | Yes         | One of the 8 model names listed above    |
| `productId` | string  | Conditional | Required for product-based models        |
| `userId`    | string  | Conditional | Required for user-based models           |
| `limit`     | integer | No          | Max results to return (1–50, default 10) |

## Response Format

```json theme={null}
{
  "model": "similar",
  "hits": [
    {
      "objectID": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Tênis Running Pro",
      "price": 299.9,
      "currency": "BRL",
      "availability": "in_stock"
    }
  ],
  "nbHits": 8,
  "fallback": false,
  "processingTimeMs": 45
}
```

| Field              | Type    | Description                                                 |
| ------------------ | ------- | ----------------------------------------------------------- |
| `model`            | string  | The model used to generate results                          |
| `hits`             | array   | Array of `SearchHit` objects (Algolia-compatible)           |
| `nbHits`           | integer | Total number of results                                     |
| `fallback`         | boolean | True when an event-based model fell back to a catalog model |
| `fallbackModel`    | string  | The fallback model used (only when `fallback=true`)         |
| `processingTimeMs` | integer | Processing time in milliseconds                             |