Recommend items for a user or device
const url = 'https://your-tenant-host/v1/recommendations?scenario=read-next&count=5';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url 'https://your-tenant-host/v1/recommendations?scenario=read-next&count=5' \ --header 'Authorization: Bearer <token>'Recombee’s recommendations, for Braze Connected Content and server-rendered pages. The site is the API key’s pin. Subject: userId, else domainUserId; neither is an empty 200 and no Recombee call. Only the site’s items that are not deleted are recommended, narrowed by the optional feed filter params (OR within a param, AND across); the scenario, authored in Recombee, adds its own filters on top. An answer is cached for 15 minutes per key site and full URL, so edition makes one edition’s renders share one answer and one recommId. /edgekit/v1/recommendations is the browser mount: the x-edgekit-site-id header and origin allowlist, the subject the EdgeKit session (none at an external_only site), else domainUserId, never cached. Every call spends the organization’s Recombee quota. A Recombee timeout or outage is a 503 with Retry-After.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Query Parameters
Section titled “Query Parameters”An item in any of these sections.
An item in any of these sections.
An item with any of these tags.
An item with any of these tags.
An item by any of these authors.
An item by any of these authors.
An item of any of these types.
An item of any of these types.
No item in these sections.
No item in these sections.
No item with these tags.
No item with these tags.
No item of these types.
No item of these types.
An item in any of these languages.
An item in any of these languages.
Only items first published at or after this instant.
Only items first published at or after this instant.
Only items first published at or before this instant.
Only items first published at or before this instant.
Leave out items the subject already viewed, as Recombee knows them. Needs Recombee’s interaction ReQL functions enabled on the database.
Leave out items the subject already viewed, as Recombee knows them. Needs Recombee’s interaction ReQL functions enabled on the database.
A scenario authored in the organization’s Recombee admin UI, passed through. An unknown one is 422.
Example
read-nextA scenario authored in the organization’s Recombee admin UI, passed through. An unknown one is 422.
Example
5The article being read: items to item (“read next”) for the subject, rather than items for the subject alone.
The article being read: items to item (“read next”) for the subject, rather than items for the subject alone.
The signed-in user, on this keyed mount only; the browser mount reads its session.
The signed-in user, on this keyed mount only; the browser mount reads its session.
The anonymous device, from the tracker’s getDomainUserId(). Read when no user is.
The anonymous device, from the tracker’s getDomainUserId(). Read when no user is.
Unread: part of the URL, so one edition’s renders share one cached answer.
Unread: part of the URL, so one edition’s renders share one cached answer.
Responses
Section titled “Responses”Recommended items, best first. Empty with no subject or nothing to recommend.
object
Recombee’s id for this answer, already on every url. Null when there was no subject to ask about.
object
The Recombee item id.
The canonical URL with recomm_id appended.
Example generated
{ "recommId": "example", "items": [ { "id": "example", "headline": "example", "description": "example", "image": "example", "url": "example", "publishedAt": "2026-04-15T12:00:00Z" } ]}Invalid request.
object
object
Example
{ "error": { "code": "unauthorized", "message": "Invalid or missing API key." }}Missing or invalid credential.
object
object
Example
{ "error": { "code": "unauthorized", "message": "Invalid or missing API key." }}Not allowed.
object
object
Example
{ "error": { "code": "unauthorized", "message": "Invalid or missing API key." }}Resource not found.
object
object
Example
{ "error": { "code": "unauthorized", "message": "Invalid or missing API key." }}Request validation failed.
object
object
Example
{ "error": { "code": "unauthorized", "message": "Invalid or missing API key." }}Unexpected error.
object
object
Example
{ "error": { "code": "unauthorized", "message": "Invalid or missing API key." }}With Retry-After, briefly unavailable; without it, not configured.
object
object
Example
{ "error": { "code": "unauthorized", "message": "Invalid or missing API key." }}