> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Lesson 7: Recommendations

> Suggest relevant books, articles, podcasts and videos from your own content, or from Gloo's publisher network, with the Recommendations APIs.

## "You Might Also Like"

A good answer is often only the start. Someone who asks how to talk with their teenager about faith may want a book on the subject, a sermon series or a podcast episode to listen to on the drive home.

**Recommendations** suggest whole items, such as books, articles, videos and podcast episodes, that match what a person is asking about. They're how you build "recommended reading" panels, related-resource lists and "you might also like" sections.

On Gloo, recommendations come from content in the **Data Engine**, the part of Gloo that stores and indexes your uploaded content (AI 103 covered how that works). You'll need content there, and Data Engine access, to use your own publisher's items.

***

## Core Concepts

### Items and Snippets

When content goes into the Data Engine, each item is split into **snippets**: meaningful sections that can be searched by meaning. A book might become hundreds of snippets; a short article, a few.

The Recommendations APIs search the snippets for your query, then group the matches by the item they came from. Items are ranked by:

1. **How many relevant snippets** they have. An item with ten matching sections ranks above one with two.
2. **Cumulative certainty**, as a tiebreaker. Each snippet has a **certainty** score saying how well it matches the query; cumulative certainty is the sum for the item.

### Three Endpoints

| Endpoint | What it returns | Whose content |
| :- | :- | :- |
| `POST /ai/v1/data/items/recommendations/base` | Ranked items with snippet metadata, without the snippet text | Your organization's publishers only |
| `POST /ai/v1/data/items/recommendations/verbose` | The same, plus the snippet text, for previews | Your organization's publishers only |
| `POST /ai/v1/data/affiliates/referenced-items` | Ranked items from across Gloo's publisher network | Publishers who allow their content to be referenced |

The two **item** endpoints only return items your organization has access to. The **affiliate** endpoint is for pointing people to resources beyond your own library, and it never returns snippet text.

### Recommendations, Search or a Grounded Answer?

All three search your content by meaning, but return different things:

* **Search** returns the matching passages themselves.
* **Grounded Responses** returns an answer written from those passages.
* **Recommendations** return the items worth opening next.

Many apps use two together: a grounded answer, then a short list of recommended resources under it.

***

## Get Started

You'll need your **tenant**, which is your publisher's name. Find it on the [Organizations page](https://docs.gloo.com/studio/manage-publishers.md) in Gloo AI Studio under **View Publishers**. The collection is always `GlooProd`.

```bash theme={null}
pip install requests
```

```python Python theme={null}
import os
import requests

API_KEY = os.environ["GLOO_API_KEY"]
TENANT = os.environ["GLOO_TENANT"]  # your publisher (tenant) name

response = requests.post(
    "https://platform.ai.gloo.com/ai/v1/data/items/recommendations/base",
    headers={"Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json"},
    json={
        "query": "How do I talk with my teenager about faith?",
        "collection": "GlooProd",
        "tenant": TENANT,
        "item_count": 3,
        "certainty_threshold": 0.5,
    },
    timeout=60,
)
response.raise_for_status()

for item in response.json():
    top = item["uuids"][0] if item.get("uuids") else {}
    print(f"{item['type']} from {item['publisher']}: {top.get('ai_title', item['item_id'])}")
    print(f"  {item['snippet_count']} matching snippets, certainty {item['cumulative_certainty']:.2f}")
```

Each item in the response looks like this:

```json theme={null}
{
  "item_id": "c42fc709-01dd-4eb1-94ab-01e076e141da",
  "publisher": "Test New Tenant",
  "type": "Book",
  "uuids": [
    {
      "uuid": "eca2616f-823a-5800-b7b2-c0c80ad84ec4",
      "ai_title": "Understanding God's Plan: It's Simpler Than You Think",
      "item_summary": "The divine plan manifests through our daily acts of goodness...",
      "certainty": 0.7546200752258301
    }
  ],
  "snippet_count": 1,
  "cumulative_certainty": 0.7546200752258301
}
```

To show a preview of each item, call the `/verbose` endpoint instead. It adds the `snippet` text to each entry in `uuids`, and lets you filter and sort, for example newest first with `"sort_by": "publication_date"`.

To recommend from the wider publisher network, call the affiliate endpoint. It doesn't take a `collection` or `tenant`:

```bash cURL theme={null}
curl -X POST 'https://platform.ai.gloo.com/ai/v1/data/affiliates/referenced-items' \
  -H "Authorization: Bearer $GLOO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "How do I have a good marriage?",
    "media_types": ["article", "book"],
    "min_snippet_count_per_item": 2,
    "certainty_threshold": 0.3,
    "item_count": 3
  }'
```

Affiliate items include display fields such as `item_title`, `author`, `item_url` and `item_image`, ready for a resource card.

***

## Good to Know

* **No results? Lower the threshold.** `certainty_threshold` filters out weaker matches. If you get nothing back, try a lower value, and test the same query in the [Search Playground](https://docs.gloo.com/studio/playground-search.md) to confirm your content is indexed.
* **Filter by format.** `media_types` limits results to `audio`, `video`, `book` or `article`.
* **Ask for fewer, better items.** `item_count` caps the list, and `min_snippet_count_per_item` drops items with only a passing mention.
* **New network content takes time.** Once a publisher allows their content to be referenced, it can take up to 24 hours to appear in results.
* **Stay in your own tenant.** The item endpoints return `403` for a tenant your organization doesn't own.

***

## Key Takeaway

Recommendations point people to whole resources, ranked by how many relevant snippets each one has. Use `/recommendations/base` for clean lists from your own content, `/recommendations/verbose` for previews, and the affiliate endpoint for resources from across Gloo's publisher network.

> [!TIP]
>
> **Try it on Gloo:** the [Building Custom Recommendations](https://docs.gloo.com/tutorials/recommendations.md) tutorial builds a recommender with a browser front end, with working code in six languages.

***

## Learn more

* [Item Recommendations](https://docs.gloo.com/api-guides/item-recommendations.md): ranked items from your own publishers, with or without snippet text
* [Affiliate Recommendations](https://docs.gloo.com/api-guides/affiliate-recommendations.md): resources from across Gloo's publisher network
* [Building Custom Recommendations](https://docs.gloo.com/tutorials/recommendations.md): a full recommender with a browser front end

***

## What's next

Next, you'll learn how token pricing works, how prompt caching lowers it, and how to pick the right model and reasoning effort for each job.

> [card] [Lesson 8: Cost and Speed](https://docs.gloo.com/ai-learning-center/gloo-ai-104/cost-and-speed.md)
>
> Token pricing, prompt caching, choosing a model and reasoning effort.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.