API Reference

Explore every endpoint in the Raccomando REST API. All requests use JSON and require a Bearer token for authentication.

Back to Documentation

Authentication

Manage API keys and access tokens. Every request must include a valid Bearer token in the Authorization header.

POST/auth/token
Exchange API key for a short-lived access token.
POST/auth/revoke
Revoke an active access token.

Products

Import, update, and manage your product catalog. Raccomando uses your catalog to build recommendation and search indexes.

GET/products
List all products with pagination and filtering.
POST/products
Create or bulk-upsert products into the catalog.
GET/products/:id
Retrieve a single product by its ID.
DELETE/products/:id
Remove a product from the catalog and all indexes.

Recommendations

Fetch AI-powered product recommendations. Supports homepage, product-detail, cart, and custom contexts.

GET/recommend
Get personalized recommendations for a user.
GET/recommend/similar
Get products similar to a given product.
GET/recommend/trending
Get globally trending products based on recent activity.

Search

Typo-tolerant, AI-ranked product search with facets, filters, and synonym support out of the box.

GET/search
Full-text search across your product catalog.
GET/search/suggest
Autocomplete suggestions as the user types.
POST/search/synonyms
Add or manage synonym groups for improved recall.

Analytics

Track user interactions and measure recommendation performance. Send events and query aggregated metrics.

POST/events
Record impression, click, add-to-cart, or purchase events.
GET/metrics
Get high-level performance metrics and KPIs.
GET/metrics/attribution
Revenue attribution report for recommendation-driven conversions.