Recommendation API

POST /v1/recommend

Your agent sends what the user asked for, a category and the recent messages, and gets up to five recommendations back to show in the chat. Give your model a recommend tool with a query, a category and an optional location. When the model calls it, send them here from your server with the last messages of the conversation, and show each recommendation as a card whose button opens its url.

Base URL

https://api.elo.ad/v1

Key

Create your publisher API key on the Integration page of the Elo dashboard. Rotating it there revokes the previous key immediately. Send it in Authorization: Bearer or in X-API-Key.

Caution

The key is for your server. Never ship it inside a mobile app or a web page.

Categories

Category	What comes back
product	Products from Elo’s product search, in order of relevance.
travel	Hotels, flights, tours and other things booked for a trip.
place	Local places to go, such as restaurants, cafes, bars, shops, museums and parks.
service	Services someone is hired for, such as a plumber, a tutor or a lawyer.

Products are real: each url is the store’s page. When Elo has turned on monetized links for your account, it can be a tracked link to the same page instead, which never changes which products come back or their order.

Travel, places and services are sample data for now. Elo makes up five items that match the request, with invented names, source set to Sample data and links on example.com, so you can build and test the card before real data arrives.

Request

curl -X POST "https://api.elo.ad/v1/recommend" \
  -H "Authorization: Bearer elo_pub_..." \
  -H "Content-Type: application/json" \
  -d '{
    "query": "running shoes under $100",
    "category": "product",
    "messages": [
      { "role": "user", "content": "I am training for my first half marathon." },
      { "role": "assistant", "content": "A cushioned daily trainer is a good place to start." },
      { "role": "user", "content": "Any running shoes under $100?" }
    ]
  }'

Field	Description
query	What the user asked for, such as running shoes under $100. Required, 1 to 2048 characters.
category	product, travel, place or service. Required.
location	Where the user wants it, such as Lisbon, up to 200 characters. Used for travel, places and services; product search ignores it and searches US stores.
messages	The last messages of the conversation, up to 10. Each is { "role", "content" }, with role user or assistant and content up to 4000 characters. Defaults to none.

Header	Description
Authorization	Bearer and your publisher key. X-API-Key with the key works too.
X-Elo-Message-Id, X-Elo-Visitor-Id	Optional. If you also serve Elo ads, the triggering message and the visitor, so a product search is added to that user’s profile for ad targeting.

Response

{
  "request_id": "3f2b8c1e-6a4d-4e2b-9c7f-1d5e8a0b2c4d",
  "category": "product",
  "recommendations": [
    {
      "title": "Brooks Ghost 16 Running Shoe",
      "description": null,
      "url": "https://www.zappos.com/p/brooks-ghost-16/...",
      "source": "Zappos",
      "next_action": "click",
      "image_url": "https://images.example.com/brooks-ghost-16.jpg",
      "price": "$99.95"
    }
  ],
  "reason": null
}

Field	Description
request_id	Identifies the call in Elo’s logs, the same value as the X-Request-ID response header. Quote it when reporting a problem.
category	The category you sent.
recommendations	Up to 5 recommendations. Empty when nothing matched or the search failed.
reason	Why recommendations is empty, short enough to show the user. null otherwise.

Each recommendation:

Field	Description
title	The item’s name.
description	One line about the item, or null. Products have none.
url	Where the item’s button goes.
source	The store for a product, or the link’s host when the store is not known. Sample data for travel, places and services.
next_action	What the button does. Always click: open url in a new tab.
image_url	A picture of the item, or null. Sample data has none.
price	The price as the source shows it, such as $99.95 or $180 a night, or null.

Sample data

curl -X POST "https://api.elo.ad/v1/recommend" \
  -H "Authorization: Bearer elo_pub_..." \
  -H "Content-Type: application/json" \
  -d '{ "query": "hotel in Lisbon next weekend", "category": "travel", "location": "Lisbon" }'

One of the five recommendations that come back:

{
  "title": "Casa Azul Hotel",
  "description": "Boutique hotel in Alfama with river views and a rooftop bar.",
  "url": "https://example.com/travel/casa-azul-hotel",
  "source": "Sample data",
  "next_action": "click",
  "image_url": null,
  "price": "$180 a night"
}

No recommendations

When nothing matches, or product search or the sample data is unavailable, the answer is still 200, with no recommendations and a reason, so your agent can tell the user and carry on.

{
  "request_id": "9a1c4e7b-2d3f-4b8a-8e6c-5f0d7b9a1c3e",
  "category": "product",
  "recommendations": [],
  "reason": "No products matched the request."
}

Errors

Status	Meaning
401	The publisher API key is missing or not valid.
422	The request does not match the schema. The body says which field.
5xx	Elo could not answer. Retry later.