Overview

The Item Recommendations endpoints provide similar functionality to the Affiliate Recommendations API, but with a key difference: it only returns items that your organization has access to. This protects intellectual property while enabling powerful content discovery features for your users. The search and ranking logic, based on snippet count and cumulative certainty, is identical to the Affiliate Recommendations API. Please note that 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.

Endpoints

There are two distinct endpoints for item recommendations:

/recommendations/base: Returns item and snippet metadata but keeps the snippet text itself hidden.
/recommendations/verbose: Returns item and snippet data, including the full snippet text.

How to Use the API

Parameters

Parameter	Description	Required
`query`	The prompt that the user enters into the application.	Yes
`collection`	The collection to search in.	Yes
`tenant`	The tenant to search. Required only for multi-tenant collections (e.g. `GlooProd`).	Conditional
`publishers`	A list of Publisher Names. Only publishers belonging to your organization are allowed.	No
`max_snippet_count_overall`	The maximum number of snippets to search through overall.	No
`certainty_threshold`	The minimum certainty threshold for snippets.	No
`media_types`	An array of media types to filter by (`audio`, `video`, `book`, `article`).	No
`min_snippet_count_per_item`	The minimum number of snippets an item must have to be returned. Must be at least 1.	No
`item_count`	The maximum number of items to return, ranked by cumulative certainty. If the available snippets span fewer items than this count, only those items are returned.	No
`item_extra_contains`	(Verbose endpoint only) A list of case-sensitive substrings matched against each item’s raw `item_extra` text. All entries must match for an item to be returned. Filtering is applied server-side, so paging operates on the filtered set. The `*` and `?` wildcard characters are rejected with a 422 response.	No
`sort_by`	(Verbose endpoint only) The ordering applied to returned items: `relevance` (default) ranks by matching snippet count, then cumulative certainty; `publication_date` orders by each item’s best-effort parsed publication date, with items whose date is empty or unparseable always sorted last. `publish_date` is accepted as an alias for `publication_date`.	No
`sort_order`	(Verbose endpoint only) The sort direction, applied only when `sort_by` is `publication_date`: `desc` (default) returns newest items first, `asc` returns oldest first.	No

Making a Request

Before making a request, you must know which publisher’s content you would like to query.

Find Your Tenant (Publisher Name): First, navigate to the Organizations page in Studio and click “View Publishers”. Your Tenant is the name of the publisher you’re querying.
Identify the Collection: A collection is where we keep the content for our customers. The only collection you’ll need to specify in requests is GlooProd. You must specify this in the collection field.

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.

An API key is necessary to call these endpoints. You can get one from the API Keys page in Gloo AI Studio and send it directly as a Bearer token.

Base Recommendations

This endpoint returns snippet metadata without the snippet text. POST /ai/v1/data/items/recommendations/base

Example Request (`/base`)

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
}'

Example Response (`/base`)

As shown below, the uuids array contains snippet metadata, but not the snippet text itself.

[
  {
    "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

Example Request (`/verbose`)

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.

Example Response (`/verbose`)

Note the addition of the snippet field in the uuids array, and the item’s raw item_extra text (which may be an empty string).

[
  {
    "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",
        "snippet": "This way of thinking about \"God's plan for your life\" is guaranteed to give us a headache—and it's just not how he operates. It's not that God's holding the treasure map and we have to guess the route to the X that marks the spot...",
        "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.7546232342720032
      }
    ],
    "snippet_count": 1,
    "cumulative_certainty": 0.7546232342720032,
    "item_extra": "visibleOnApps:true"
  }
]

Use Cases

The Item Recommendations API is ideal for a publisher looking to increase exposure and engagement with their own content. For example, a user could enter a query on a publisher’s website. The publisher could then use the /recommendations/base endpoint to recommend their own relevant books, articles, or videos. This enhances content discovery and keeps users engaged on the platform. If the publisher wanted to provide a preview of 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.

Get Started

Completions & Responses

Content

Organization & Billing

GlooCode

Learn More

External

Legacy

Item Recommendations

Overview

Endpoints

How to Use the API

Parameters

Making a Request

Base Recommendations

Example Request (`/base`)

Example Response (`/base`)

Verbose Recommendations

Example Request (`/verbose`)

Example Response (`/verbose`)

Use Cases

​Overview

​Endpoints

​How to Use the API

​Parameters

​Making a Request

​Base Recommendations

​Example Request (/base)

​Example Response (/base)

​Verbose Recommendations

​Example Request (/verbose)

​Example Response (/verbose)

​Use Cases

Overview

Endpoints

How to Use the API

Parameters

Making a Request

Base Recommendations

Example Request (`/base`)

Example Response (`/base`)

Verbose Recommendations

Example Request (`/verbose`)

Example Response (`/verbose`)

Use Cases