Skip to main content
The Item Recommendations endpoints work like the Affiliate Recommendations API, with one key difference: they only return items that your organization has access to. This protects intellectual property while still giving your users content discovery. The Item Recommendations API suits a publisher who wants more exposure and engagement for their own content. For example, when a user enters a query on a publisher’s website, the publisher can use the /recommendations/base endpoint to recommend their own relevant books, articles, or videos. To preview the content, they could use the /recommendations/verbose endpoint to display a relevant snippet or a sample of one, encouraging the user to explore the full item. Ranking (by snippet count, then cumulative certainty) is identical to the Affiliate Recommendations API. The Recommendations lesson in the AI Learning Center explains it and when to use each endpoint.

Before you start

First, find which publisher’s content you want to query.
  1. Find Your Tenant (Publisher Name): Go to the Organizations page in Studio and click “View Publishers”. Your Tenant is the name of the publisher you’re querying.
  2. Identify the Collection: A collection is where we keep customer content. Set the collection field to GlooProd, the only collection you need.
You will only have access to your own publisher’s tenant through this endpoint. For multi-tenant collections such as GlooProd, a tenant must be specified; requests outside your tenant return a 403 “Forbidden” response.
These endpoints need an API key. Get one from the API Keys page in Gloo AI Studio and send it as a Bearer token. Once a publisher allows their content to be used as a reference, it may take up to 24 hours for search queries to include their items in returned data.

Quick start: base recommendations

This endpoint returns snippet metadata without the snippet text. POST /ai/v1/data/items/recommendations/base
The uuids array in the response contains snippet metadata, but not the snippet text.

Verbose recommendations

This endpoint returns the full snippet text. POST /ai/v1/data/items/recommendations/verbose
The request above keeps only items whose item_extra text contains visibleOnApps:true and returns them newest-first by publication date. The response has the same shape as /base, with two additions: each entry in uuids carries the snippet text, and each item carries its raw item_extra text (which may be an empty string). See the verbose API reference for the full response.

Parameters

Send query and collection (plus tenant for a multi-tenant collection such as GlooProd). The optional fields filter by publisher and media type, set a certainty threshold, and decide how many snippets are searched and how many items come back. /verbose also takes item_extra_contains, sort_by and sort_order. For every field and its default, see the API reference for base and verbose recommendations.

Next steps

Call this endpoint from your server so your key stays private, as API Key Security describes, and see Error Handling and Retries for which failed requests to retry.

Affiliate Recommendations

Recommend items from the affiliate network.

Step-by-step tutorial

Build a recommender with code in six languages.

API Reference

Request and response details.