Skip to main content
POST
Get Verbose 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 verbose 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
item_extra_contains
string[]

Case-sensitive substring filters matched against each item's raw item_extra text. All entries must match (AND) for an item to be returned. Filtering is applied during the search, so max_snippet_count_overall counts only matching snippets. The wildcard characters * and ? are not permitted and return a 422 response.

Minimum string length: 1
Example:
sort_by
enum<string>
default:relevance

The ordering applied to returned items. relevance ranks by 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.

Available options:
relevance,
publication_date
sort_order
enum<string>
default:desc

The sort direction, applied only when sort_by is publication_date. desc returns newest items first; asc returns oldest first.

Available options:
asc,
desc

Response

Successful response returning a list of items with full snippet text.

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
ItemRecommendationUuidVerbose · object[]
item_extra
string

The item's raw item_extra text. May be an empty string.