> ## 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.

# Item Recommendations

> Guide to surfacing relevant content from your organization’s own data

The Item Recommendations endpoints work like the [Affiliate Recommendations API](https://docs.gloo.com/api-guides/affiliate-recommendations.md), with one key difference: **they only return items that your [organization](https://docs.gloo.com/getting-started/glossary.md#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](https://docs.gloo.com/ai-learning-center/gloo-ai-104/recommendations.md) lesson in the AI Learning Center explains it and when to use each endpoint.

| Endpoint | Returns |
| - | - |
| **`/recommendations/base`** | Item and snippet metadata, but keeps the snippet text itself hidden. |
| **`/recommendations/verbose`** | Item and snippet data, **including** the full snippet text. |

## Before you start

First, find which publisher's content you want to query.

1. **Find Your Tenant (Publisher Name):** Go to the [Organizations page](https://docs.gloo.com/studio/manage-publishers.md) in Studio and click "View Publishers". Your **[Tenant](https://docs.gloo.com/getting-started/glossary.md#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.

> [!NOTE]
>
> 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](https://docs.gloo.com/studio/manage-api-credentials.md). 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`

```bash theme={null}
curl -X 'POST' \
  'https://platform.ai.gloo.com/ai/v1/data/items/recommendations/base' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $GLOO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "collection": "GlooProd",
  "max_snippet_count_overall": 10,
  "media_types": [],
  "min_snippet_count_per_item": 1,
  "publishers": ["Test New Tenant"],
  "query": "Plans God has for me",
  "tenant": "TestNewTenant",
  "certainty_threshold": 0.5,
  "item_count": 3
}'
```

The `uuids` array in the response contains snippet metadata, but not the snippet text.

> [accordion] Example response (/base)
>
> ```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",
>         "ai_subtitle": "Why Finding God's Will Isn't a Treasure Hunt",
>         "item_summary": "The divine plan manifests through our daily acts of goodness, rather than existing as a predetermined sequence we must discover.",
>         "time_start": "",
>         "time_end": "",
>         "part": 128,
>         "certainty": 0.7546200752258301
>       }
>     ],
>     "snippet_count": 1,
>     "cumulative_certainty": 0.7546200752258301
>   }
> ]
> ```

## Verbose recommendations

This endpoint returns the full snippet text.

`POST /ai/v1/data/items/recommendations/verbose`

```bash theme={null}
curl -X 'POST' \
  'https://platform.ai.gloo.com/ai/v1/data/items/recommendations/verbose' \
  -H 'accept: application/json' \
  -H "Authorization: Bearer $GLOO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "collection": "GlooProd",
  "max_snippet_count_overall": 10,
  "media_types": [],
  "min_snippet_count_per_item": 1,
  "publishers": ["Test New Tenant"],
  "query": "Plans God has for me",
  "tenant": "TestNewTenant",
  "certainty_threshold": 0.5,
  "item_count": 3,
  "item_extra_contains": ["visibleOnApps:true"],
  "sort_by": "publication_date",
  "sort_order": "desc"
}'
```

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](https://docs.gloo.com/api-reference/data/get-verbose-item-recommendations.md) for the full response.

## Parameters

Send `query` and `collection` (plus `tenant` for a multi-tenant [collection](https://docs.gloo.com/getting-started/glossary.md#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](https://docs.gloo.com/api-reference/data/get-base-item-recommendations.md) and [verbose](https://docs.gloo.com/api-reference/data/get-verbose-item-recommendations.md) recommendations.

## Next steps

Call this endpoint from your server so your key stays private, as [API Key Security](https://docs.gloo.com/best-practices/api-key-security.md#keep-the-key-on-the-server) describes, and see [Error Handling and Retries](https://docs.gloo.com/best-practices/error-handling-and-retries.md) for which failed requests to retry.

> [card] [Affiliate Recommendations](https://docs.gloo.com/api-guides/affiliate-recommendations.md)
>
> Recommend items from the affiliate network.

> [card] [Step-by-step tutorial](https://docs.gloo.com/tutorials/recommendations.md)
>
> Build a recommender with code in six languages.

> [card] [API Reference](https://docs.gloo.com/api-reference/data/get-base-item-recommendations.md)
>
> Request and response details.


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