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

# VTEX IO Installation

> Install the Alana Search resolver app on VTEX IO to replace native search with AI-powered semantic search

## Prerequisites

* VTEX IO CLI (`vtex`) installed and authenticated
* VTEX store on IO framework
* Alana API key (search-only key from workspace settings)
* **`vtex.search-resolver@0.x` must NOT be installed** — the Alana resolver conflicts with VTEX's native search resolver

## Conflict Check

Before installing, verify that `vtex.search-resolver@0.x` is not active:

```bash theme={null}
vtex ls | grep search-resolver
```

If it appears in the output, uninstall it first:

```bash theme={null}
vtex uninstall vtex.search-resolver@0.x
```

## Installation

```bash theme={null}
vtex install alana.search-resolver@0.x
```

## Configuration

After installation, configure your API credentials via the VTEX Admin panel:

1. Go to **Apps → My Apps → Alana Search Resolver**
2. Set **Alana API Key** (required) — your `ak_xxx` key
3. Set **Alana API URL** (optional) — defaults to `https://app.alana.shopping`
4. Save and wait \~30 seconds for propagation

Or configure via CLI:

```bash theme={null}
vtex settings set alana.search-resolver alanaApiKey "ak_your_api_key"
vtex settings set alana.search-resolver alanaApiUrl "https://app.alana.shopping"
```

## Resolver Mapping

The Alana app implements the VTEX Search Protocol GraphQL resolvers and proxies them to the Alana Search API v1:

| VTEX Resolver                   | Alana Endpoint             | Notes                                        |
| ------------------------------- | -------------------------- | -------------------------------------------- |
| `productSearch`                 | `POST /api/v1/search`      | `from/to` mapped to `page/hitsPerPage`       |
| `facets`                        | `POST /api/v1/search`      | `hitsPerPage: 0` — facets only               |
| `autocompleteSearchSuggestions` | `GET /api/v1/autocomplete` | `limit: 10`                                  |
| `searchSuggestions`             | `GET /api/v1/autocomplete` | `limit: 5` with product previews             |
| `topSearches`                   | `GET /api/v1/search`       | Returns trending queries                     |
| `correction`                    | `POST /api/v1/search`      | `hitsPerPage: 0` — extracts `correctedQuery` |

## OrderBy Mapping

VTEX `OrderBy` strings are automatically translated to Alana sort values:

| VTEX OrderBy              | Alana `sortBy` |
| ------------------------- | -------------- |
| `OrderByTopSaleDESC`      | `relevance`    |
| `OrderByReleaseDateDESC`  | `newest`       |
| `OrderByBestDiscountDESC` | `relevance`    |
| `OrderByPriceDESC`        | `price_desc`   |
| `OrderByPriceASC`         | `price_asc`    |
| *(all others)*            | `relevance`    |

## Caching

`@cacheControl` directives are set per resolver:

| Resolver                                             | TTL   |
| ---------------------------------------------------- | ----- |
| `productSearch`, `facets`                            | 120 s |
| `autocompleteSearchSuggestions`, `searchSuggestions` | 60 s  |
| `topSearches`                                        | 300 s |
| `correction`                                         | 120 s |

## Troubleshooting

**Search returns empty results**

* Verify the API key is set in App Settings
* Check that the catalog has been indexed (Workspace → Products → Sync)

**`vtex.search-resolver@0.x` conflict error**

* Uninstall the native resolver before installing Alana: `vtex uninstall vtex.search-resolver@0.x`

**Resolver returns 401**

* The API key in App Settings is incorrect or expired
* Generate a new search-only API key in Alana workspace settings

**Facets are empty**

* Ensure facet configs have been created via `/api/v1/facets/config` for your workspace