Pular para o conteúdo principal
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

MethodPathDescription
GET/api/v1/facets/configList all facet configurations
POST/api/v1/facets/configCreate a facet configuration
PUT/api/v1/facets/config/Update a facet configuration
DELETE/api/v1/facets/config/Delete a facet configuration

​
FacetConfig Object

FieldTypeDescription
iduuidConfiguration ID
workspace_iduuidOwning workspace
attribute_keystringProduct attribute key (e.g., brand, color)
display_namestringHuman-readable label shown in filter UI
facet_typeenumOne of: value, range, hierarchical
sort_orderintegerDisplay order (lower = first)
enabledbooleanWhether this facet is active in search responses
created_atstringISO 8601 creation timestamp

​
facet_type Values

ValueDescription
valueExact match counts (e.g., brand: Nike=42, Adidas=18)
rangeNumeric buckets (e.g., price: 0-50=5, 50-100=12)
hierarchicalCategory tree counts using category_path array

​
GET /api/v1/facets/config

List all facet configurations for the authenticated workspace. 
curl https://alana.shopping/api/v1/facets/config \
  -H "x-api-key: ak_your_api_key"

{
  "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. 
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/

Update an existing facet configuration. 
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/

Delete a facet configuration. Returns 204 No Content. 
curl -X DELETE https://alana.shopping/api/v1/facets/config/fc_01abc \
  -H "x-api-key: ak_your_api_key"
Once configured, request facet counts in POST /api/v1/search: 
{
  "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.
Last modified on March 12, 2026