Skip to main content
POST
Get Base Item Recommendations

Guide: Item Recommendations

Base and verbose recommendations, parameters, and example requests and responses.

Error Reference: Search & Recommendations

Common errors: invalid collection, missing or invalid tenant, certainty threshold issues, empty query string.

Authorizations

Authorization
string
header
default:Bearer <api-key>
required

Bearer authentication header of the form Bearer <api-key>, where <api-key> is your API key.

Body

application/json

Parameters for retrieving base item recommendations.

query
string
required

The prompt that the user enters into the application.

Minimum string length: 1
collection
string
required

The collection to search in.

Minimum string length: 1
certainty_threshold
number
default:0.5

The minimum certainty threshold for snippets.

Required range: 0 <= x <= 1
tenant
string

Optional tenant to search. Required only when the selected collection is multi-tenant; invalid when the selected collection is not multi-tenant. Blank strings are normalized to no tenant.

publishers
string[]

A list of Publisher Names. Only publishers belonging to your organization are allowed.

Minimum string length: 1
max_snippet_count_overall
integer
default:10

The maximum number of snippets to search through overall.

Required range: x >= 1
min_snippet_count_per_item
integer
default:1

The minimum number of snippets for an item to be returned.

Required range: x >= 1
media_types
enum<string>[]

The type(s) of media for the items returned.

Available options:
audio,
video,
book,
article
item_count
integer

The maximum number of items to return. Items are ranked by snippet_count, then cumulative certainty (on the verbose endpoint, sort_by can order them by publication date instead). If the available snippets span fewer items than this count, only those items are returned.

Required range: x >= 1

Response

Successful response returning a list of items with basic snippet metadata.

item_id
string<uuid>
author
string[]
filename
string
tradition
string
duration
string
item_title
string
item_subtitle
string
item_image
string<uri>
item_url
string<uri>
item_tags
h2_id
string
h2_title
string
h2_subtitle
string
h2_image
string<uri>
h2_url
string<uri>
h2_tags
string | null
h3_id
string
h3_title
string
h3_subtitle
string
h3_image
string<uri>
h3_url
string<uri>
h3_tags
string | null
h2_summary
string
publication_date
string
publisher
string
publisher_id
string<uuid>
publisher_url
string<uri>
item_summary
string
type
string
hosted_url
string<uri>
snippet_count
integer
cumulative_certainty
number<float>
denomination
string
uuids
ItemRecommendationUuidBase · object[]