The Algolia Recommend API returns related-products, frequently-bought-together, trending and look-alike recommendations, trained from Insights events and catalog data. It is one of 11 APIs that Algolia publishes on the network, served from https://{appid}-dsn.algolia.net.
The base URL is templated, and correctly so
{appid}-dsn.algolia.net carries braces. That matters.
Two of this week’s API deep-dives ran aground on host values: HubSpot Associations publishes api.example.com, and the Mailchimp entry covered last week publishes server.api.mailchimp.com — a plausible-looking hostname that is actually a template with no syntactic signal that it is one.
Algolia does the same thing Mailchimp does — shards customers across application-specific hosts — and marks the variable part. A client generated from this contract knows a substitution is required. An agent reading it knows there is a value it must obtain before calling.
{appid} is not a flaw. It is the correct way to describe a per-tenant host, and it takes two characters.
Recommend is the second half of an integration
The interesting thing about this API is that you cannot use it on its own.
Recommendations are trained from Insights events — the click, conversion and view signals your application sends back to Algolia — plus your catalog data. Which means the integration order is: index your catalog, wire up the Insights API, send behavioural events for long enough to accumulate a signal, and only then call Recommend and get something worth showing.
Algolia’s surface reflects that dependency cleanly. The eleven APIs decompose into the pipeline: Search and Crawler and Ingestion to get data in, Insights to send behaviour back, Analytics and A/B Testing and Monitoring to measure, and Recommend, Personalization and Query Suggestions as the outputs that depend on all of the above.
Eleven APIs that describe a loop rather than a menu.
What is missing
The published artifact set for this entry is documentation only — no OpenAPI specification registered against it.
For an API whose entire value is a small number of well-defined model types (related products, frequently bought together, trending, look-alike), each returning a scored list, a schema would be inexpensive and genuinely useful. The response shape is the integration, and there are only a handful of variants.
This is the same gap as the Klarna Settlements API covered yesterday: a well-designed API at the right boundary, described in prose.
The thing worth stealing
The design lesson here is the explicit event feedback loop. Most APIs that claim personalisation or recommendations are vague about what they train on and when the model improves. Algolia names the dependency in the API description itself — trained from Insights events and catalog data — which tells an integrator, before they write a line, that this API will return nothing useful until they have done work elsewhere.
Setting that expectation in the contract rather than in a support ticket is a small act of honesty that saves a lot of confused evaluations.
Takeaway
A correctly-templated base URL, a surface decomposed as a feedback loop rather than a feature list, and an upfront statement of what it trains on — published without a schema. Algolia got the design and the honesty right and left the machine-readable description to the docs.
Read the docs at algolia.com/doc/rest-api/recommend/, and the provider entry at apis.io/providers/algolia/.