Pular para o conteúdo principal
POST
/
api
/
v1
/
recommend
Recommendations
curl --request POST \
  --url https://api.example.com/api/v1/recommend

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

ModelTypeRequired ParamsDescription
similarCatalogproductIdProducts semantically similar to the given product
complementaryCatalogproductIdProducts that complement (go well with) the given product
alternativesCatalogproductIdAlternative products in the same category at similar price
match_profileCatalogproductIdProducts matching the same style/attribute profile
trendingCatalog—Top trending products in the workspace catalog
frequently_bought_togetherEvent-basedproductIdProducts commonly purchased alongside the given product
recommended_for_youEvent-baseduserIdPersonalized recommendations based on user behavior history
buy_it_againEvent-baseduserIdProducts 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

{
  "model": "similar",
  "productId": "550e8400-e29b-41d4-a716-446655440000",
  "limit": 10
}

​
Parameters

FieldTypeRequiredDescription
modelstringYesOne of the 8 model names listed above
productIdstringConditionalRequired for product-based models
userIdstringConditionalRequired for user-based models
limitintegerNoMax results to return (1–50, default 10)

​
Response Format

{
  "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
}
FieldTypeDescription
modelstringThe model used to generate results
hitsarrayArray of SearchHit objects (Algolia-compatible)
nbHitsintegerTotal number of results
fallbackbooleanTrue when an event-based model fell back to a catalog model
fallbackModelstringThe fallback model used (only when fallback=true)
processingTimeMsintegerProcessing time in milliseconds
Last modified on March 12, 2026