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

# Autocomplete

> Get type-ahead search suggestions with document counts

Returns term suggestions from the pre-aggregated search suggestions index. Optimized for sub-50ms response times with Redis caching.

## Authentication

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

```bash theme={null}
curl "https://alana.shopping/api/v1/autocomplete?query=cam" \
  -H "x-api-key: ak_your_api_key"
```

## Query Parameters

<ParamField query="query" type="string" required>
  Search prefix (minimum 2 characters). Returns empty suggestions for single-character queries.
</ParamField>

<ParamField query="limit" type="integer" default="5">
  Maximum number of suggestions returned. Capped at 10.
</ParamField>

<ParamField query="include_products" type="boolean" default="false">
  Include top 3 matching products when available from cache. Products are only returned on cache hit — never triggers a live search query.
</ParamField>

<ParamField query="key" type="string">
  API key as query parameter (alternative to `x-api-key` header).
</ParamField>

## Response

<ResponseField name="suggestions" type="AutocompleteSuggestion[]">
  Array of suggestion objects ordered by document count descending.
</ResponseField>

<ResponseField name="processingTimeMs" type="integer">
  Server-side processing time in milliseconds.
</ResponseField>

<ResponseField name="products" type="SearchHit[]">
  Optional product previews. Only present when `include_products=true` and cache is warm.
</ResponseField>

### AutocompleteSuggestion

| Field | Type    | Description                           |
| ----- | ------- | ------------------------------------- |
| text  | string  | Suggestion term                       |
| count | integer | Number of products matching this term |

## Example

```bash theme={null}
curl "https://alana.shopping/api/v1/autocomplete?query=camis&limit=5" \
  -H "x-api-key: ak_your_api_key"
```

```json theme={null}
{
  "suggestions": [
    { "text": "camiseta", "count": 142 },
    { "text": "camiseta azul", "count": 38 },
    { "text": "camiseta polo", "count": 24 },
    { "text": "camiseta branca", "count": 19 },
    { "text": "camiseta oversized", "count": 11 }
  ],
  "processingTimeMs": 6
}
```

## Rate Limits

1000 requests per minute per API key.

## Error Codes

| Status | Error        | Description                        |
| ------ | ------------ | ---------------------------------- |
| 400    | Bad Request  | Missing or empty `query` parameter |
| 401    | Unauthorized | Invalid or missing API key         |
| 429    | Rate Limited | Exceeded 1000 req/min per API key  |