Skip to main content
Like Search, the Affiliate Recommendations endpoint searches published materials from publishers for items semantically related to a user’s query. Use it to surface relevant content, such as “additional resources” or “recommended reading”, based on a user’s questions or interests. Publishers who filter on their own data also get more exposure for their own content; to recommend only your organization’s items, use Item Recommendations. The Recommendations lesson in the AI Learning Center compares it with the item endpoints.

Quick start

These endpoints need an API key. Get one from the API Keys page in Gloo AI Studio and send it as a Bearer token. Endpoint: POST /ai/v1/data/affiliates/referenced-items
The response is an array of item objects, sorted by relevance. Each item carries its title, author, publisher, type, URLs, snippet_count and cumulative_certainty.
This item matched on two snippets, with a cumulative certainty of about 1.4. Each item also carries its section (h2_*, h3_*), publisher (publisher_id, publisher_url, publisher_logo) and hosting details; see the API reference for every field.

How items are ranked

The endpoint returns items based on the number of matching snippets associated with each item.
  • Snippets: A snippet is a section of a content item (like a podcast episode, article, or book) that represents a meaningful piece of information our AI tools can search and understand. They are the units of searchable content in our backend.
  • Ranking Logic: Items are ranked first by the number of relevant snippets found. If two or more items have the same snippet count, they are then ranked by their cumulative certainty.
  • Certainty Score: This is a confidence metric indicating how well a snippet matches the user’s query. Higher scores mean stronger relevance. Cumulative certainty is the sum of these scores, an overall confidence measure for the item.
To protect intellectual property, the snippets themselves are not visible in the API response. For example, for the query, “How do I raise kids as a new parent?”, if a book has 10 relevant snippets, an article has 8, and a podcast has 6, the API ranks them in that order: book (10), article (8), podcast (6).

Parameters

Only query is required. The optional fields filter by publisher and media type, set a certainty threshold, and cap how many snippets are searched and how many items come back. See the API reference for every field and its default.

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.

Item Recommendations

Publisher-scoped recommendations from your own content.

Step-by-step tutorial

Build a recommender with code in six languages.

API Reference

Request and response details for affiliate referenced items.