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

# Facet Configuration

> Manage which product attributes are facetable per workspace

Configure which attributes appear as filter options in search results. Supports value facets (exact match), range facets (numeric intervals), and hierarchical facets (category trees).

## Authentication

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

## Endpoints

| Method | Path                       | Description                   |
| ------ | -------------------------- | ----------------------------- |
| GET    | /api/v1/facets/config      | List all facet configurations |
| POST   | /api/v1/facets/config      | Create a facet configuration  |
| PUT    | /api/v1/facets/config/{id} | Update a facet configuration  |
| DELETE | /api/v1/facets/config/{id} | Delete a facet configuration  |

## FacetConfig Object

| Field          | Type    | Description                                      |
| -------------- | ------- | ------------------------------------------------ |
| id             | uuid    | Configuration ID                                 |
| workspace\_id  | uuid    | Owning workspace                                 |
| attribute\_key | string  | Product attribute key (e.g., `brand`, `color`)   |
| display\_name  | string  | Human-readable label shown in filter UI          |
| facet\_type    | enum    | One of: `value`, `range`, `hierarchical`         |
| sort\_order    | integer | Display order (lower = first)                    |
| enabled        | boolean | Whether this facet is active in search responses |
| created\_at    | string  | ISO 8601 creation timestamp                      |

## facet\_type Values

| Value        | Description                                          |
| ------------ | ---------------------------------------------------- |
| value        | Exact match counts (e.g., brand: Nike=42, Adidas=18) |
| range        | Numeric buckets (e.g., price: 0-50=5, 50-100=12)     |
| hierarchical | Category tree counts using `category_path` array     |

## GET /api/v1/facets/config

List all facet configurations for the authenticated workspace.

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

```json theme={null}
{
  "configs": [
    {
      "id": "fc_01abc",
      "workspace_id": "ws_xyz",
      "attribute_key": "brand",
      "display_name": "Marca",
      "facet_type": "value",
      "sort_order": 0,
      "enabled": true,
      "created_at": "2026-03-01T00:00:00Z"
    }
  ]
}
```

## POST /api/v1/facets/config

Create a new facet configuration.

```bash theme={null}
curl -X POST https://alana.shopping/api/v1/facets/config \
  -H "x-api-key: ak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "attribute_key": "color",
    "display_name": "Cor",
    "facet_type": "value",
    "sort_order": 1
  }'
```

Returns `201 Created` with the new FacetConfig object.

## PUT /api/v1/facets/config/{id}

Update an existing facet configuration.

```bash theme={null}
curl -X PUT https://alana.shopping/api/v1/facets/config/fc_01abc \
  -H "x-api-key: ak_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"enabled": false}'
```

## DELETE /api/v1/facets/config/{id}

Delete a facet configuration. Returns `204 No Content`.

```bash theme={null}
curl -X DELETE https://alana.shopping/api/v1/facets/config/fc_01abc \
  -H "x-api-key: ak_your_api_key"
```

## Using Facets in Search

Once configured, request facet counts in `POST /api/v1/search`:

```json theme={null}
{
  "query": "camiseta",
  "facets": ["brand", "color", "price"],
  "facetFilters": [["brand:Nike", "brand:Adidas"]]
}
```

Facet counts use **disjunctive logic** — filtering by `brand:Nike` still shows all brands in the `facets.brand` response, allowing users to switch filters without losing context.