Skip to content
KismetKismetDevelopers
Beta accessllms.txt

Search bookable products

View .md

Build a results page with dates, guest count, and catalog filters. Add an optional natural-language query when visitors want to describe their ideal stay. Both modes use bookableProduct.search() and return cards in ranked. Without a query, no AI retrieval runs. Search does not create a binding quote or authorize a booking.

Optional-query browsing and cursor pagination require the unified-search API extension (v0.7.49) and an SDK build containing these options. Older deployments support the existing query/topK call only; do not silently fall back to a different result set.

Create a collection-scoped installation with search.read using Create an application and key. A browser can use an origin-bound publishable key. A backend can use a restricted server key. TEST and LIVE are separate installations; use TEST for rehearsals.

import { createKismetClient } from '@kismet-tech/sdk';
const kismet = createKismetClient({
apiKey: publishableKey,
collection: 'coastal-stays',
baseUrl: 'https://api.ksmt.app/v1',
});
const result = await kismet.bookableProduct.search({
query: 'quiet beach home with a pool',
checkIn: '2027-01-11',
checkOut: '2027-01-16',
guests: 4,
limit: 12,
});
for (const hit of result.ranked) {
console.log(hit.product.name, hit.product.servingUrl, hit.price?.stay);
}

Send both dates or neither. Explicit dates and guest count take precedence over facts inferred from the query. The operation reference describes validation and limits.

const filters = {
checkIn: '2027-01-11',
checkOut: '2027-01-16',
guests: 4,
minBedrooms: 2,
petsAllowed: true,
sort: 'name-asc' as const,
limit: 12,
};
const first = await kismet.bookableProduct.search(filters);
const next = first.page?.nextCursor
? await kismet.bookableProduct.search({ ...filters, cursor: first.page.nextCursor })
: null;

Use group or building to narrow a catalog; minBedrooms, minBathrooms, and petsAllowed are explicit filters. They narrow the authorized published inventory before semantic retrieval. An explicit minimum bedroom count or pet filter takes precedence over the corresponding inferred criterion.

The default sort is recommended without a query and relevance with one. You can also choose name-asc, bedrooms, or sleeps; bedrooms and sleeps put larger properties first. relevance requires a query. Price, map-bound, and arbitrary amenity filters are not fields on this operation.

The alternative-stays extension requires a matching API deployment and SDK build. It is additive; older deployments do not accept dateRanges.

const alternatives = await kismet.bookableProduct.search({
query: 'quiet home with a fireplace',
guests: 2,
dateRanges: [
{ checkIn: '2027-01-08', checkOut: '2027-01-10' },
{ checkIn: '2027-01-15', checkOut: '2027-01-17' },
],
limit: 12,
});
for (const hit of alternatives.ranked) {
const checkedStays = hit.stayOptions?.filter((stay) => stay.available === true) ?? [];
console.log(hit.product.name, checkedStays);
}

Send one to three ranges, each 1–90 nights, with up to 16 guests. Do not combine dateRanges with checkIn/checkOut. Duplicate ranges are checked once. Ranges are alternatives: a home available for either qualifies once. Homes with only unavailable ranges are excluded; unknown ranges remain distinguishable from unavailable ones. This works with structured destination/group filters as well as semantic queries, within the same authorized collection scope.

Each hit returns stayOptions, including dates, nights, available, checkedAt, and a nullable price. checkedAt records when the API evaluated the synced inventory; it does not assert a fresh supplier quote. available: true means at least one range fits; null means none is proven available and at least one is unknown. Each option’s price follows the existing before-tax convention. Prices are absent for unknown or unavailable options.

When no explicit dates are supplied, the API also checks two or three alternative stays named in the natural-language query. Explicit dateRanges or a checkIn/checkOut pair take precedence over inferred dates. For alternatives, price.stay remains null: render stayOptions rather than falling back to the generic nightlyFrom price. A From price must use only checked available options with comparable currency and stay length. Label the associated dates, let the guest choose an option, and recheck that exact stay before booking.

Interpretation retains wants (required versus preferred), places, dateWindow, and dateAlternatives under intent. preferredMatches on a hit describes matched optional preferences; it does not make them mandatory. placeResolution explains collection-scoped destination matching. These additive fields may be absent on older deployments.

These extensions require a matching API deployment and SDK build. Use limit for the paginated search flow. A flexible query such as “a weekend in December” checks candidate arrivals before pagination. Each qualifying home carries its first bookable stay with price.stay.source: 'window' and a checked stayOptions entry. An open-length month or range chooses the shortest bookable stay, up to seven nights, at the first qualifying arrival. The scan is bounded to 60 arrivals and a 92-day calendar span; availability.window.candidates reports the arrivals checked. It is not a promise to scan an unlimited date range. Unknown inventory remains unknown, and missing pricing is never replaced with an undated estimate.

For a follow-up, send the preceding response’s intent as previousIntent, and put only the new instruction in query:

const initialAsk = await kismet.bookableProduct.search({
query: 'a cabin for six, a weekend in December, sauna if possible',
limit: 12,
});
const amended = await kismet.bookableProduct.search({
query: 'actually for eight, no need for a sauna',
previousIntent: initialAsk.intent,
limit: 12,
});

Untouched constraints stay intact; explicit removals clear them. A new unrelated ask can reset the context. For a deliberate fresh search, omit previousIntent. SEARCH_AMENDMENT_UNAVAILABLE (503) means the interpreter could not safely apply the follow-up: retry or offer a fresh search, rather than silently dropping constraints. This is client-carried search context, not guest authentication or a persisted conversation identifier.

Thin results may include broadenings with a label, added-match count, and revised intent. To select one, send that intent with the original query and a new cursor-free request. Do not send intent and previousIntent together. Broadening dates are checked through the same scoped availability authority; unknown availability is not counted as a confirmed dated addition. No suggestion widens the installation’s collection or publication grants. An explicit group/building filter still applies.

Explicit date, guest, bedroom, and pet fields continue to override inferred context. Remove or update old explicit fields when the guest changes those constraints. Repeat the exact context and filters with a cursor; a changed intent starts a new search. Always recheck the chosen stay at checkout.

For alternatives, price.stay is null and the response intent has no single date pair. A drawer must choose an actual returned stay, then obtain a fresh quote through the supported checkout path. Never substitute the undated nightlyFrom price. If displaying “From”, compare only priced, available options with the same currency and fee/tax basis, disclose the corresponding dates and nights, and never imply the amount applies to every range.

The equivalent REST request is POST /v1/developer/collections/{collection}/search with the existing Developer authentication headers and this JSON body:

{
"query": "quiet home with a fireplace",
"guests": 2,
"dateRanges": [
{ "checkIn": "2027-01-08", "checkOut": "2027-01-10" },
{ "checkIn": "2027-01-15", "checkOut": "2027-01-17" }
],
"limit": 12
}

Ranges are included in cursor validation. Repeat them on every page; changing them starts a new search. No additional capability or guest identity is required beyond existing search.read access. TEST and LIVE remain separate installations. Mixed single-stay and alternative-stay fields, invalid calendar dates, or limits outside the supported range return VALIDATION_ERROR; correct the request rather than retrying it unchanged.

  • limit is 1–50 (default 24 for structured browsing). Supplying it opts a semantic query into pagination.
  • Repeat the same query, dates, filters, sort, and limit with each cursor. Do not use a cursor after changing a filter.
  • Results are held for five minutes. INVALID_CURSOR means the snapshot expired, parameters changed, or publication/membership changed: clear the cursor and start again.
  • page.total counts this search’s result set. Semantic retrieval is bounded, not an exhaustive inventory listing. Structured browsing covers the eligible published catalog; narrow scopes over 1,000 products with a group or building.
  • Dated availability and pricing are evaluated before pagination. Pages preserve their order and price snapshot; always recheck current availability and price at checkout.
  • Existing query/topK calls keep their bounded legacy behavior. Do not combine topK with limit.

For a vacation-rental site, use group to search a destination. For an apartment-style collection, use building to search units in a building. Neither requires a separate search implementation.

Equivalent server-side REST request:

Terminal window
curl https://api.ksmt.app/v1/developer/collections/coastal-stays/search \
-H "Authorization: Bearer $KISMET_SECRET_KEY" \
-H 'Content-Type: application/json' \
-d '{"query":"quiet beach home with a pool","checkIn":"2027-01-11","checkOut":"2027-01-16","guests":4,"limit":12}'
  • Preserve ranked order and returned relaxation flags; a relevance score is not availability.
  • Paginated results include available: true means the synced stay rules fit, null means unknown or no dates. Known-unavailable homes are excluded before paging; never label unknown inventory as sold out. Dated search supports 1–90 nights and up to 16 guests.
  • mode: 'structured' has a score of zero meaning unscored, not low quality. Structured cards may have no servingUrl or undated price; use your own property route and omit missing prices.
  • Use product.bathrooms, location, and homeCollection when present. Do not infer collection membership from names or URLs.
  • price.stay.totalBeforeTaxMinor includes required fees but excludes taxes. nightlyMinor is the corresponding nightly display amount. Amounts are integer minor units with a currency; do not compare different currencies.
  • price.nightlyFrom is an undated indicative amount with its own horizon. Do not substitute it for a missing dated stay price.
  • Null or absent prices mean no price to display, not zero or sold out. Recheck availability and current pricing through the supported checkout path.
  • Older API responses may omit newer card or capture fields. The SDK preserves those omissions rather than inventing defaults.

Optionally record the search on a guest journey

Section titled “Optionally record the search on a guest journey”

Pass the existing canonical kid_ session as guestSessionId when available. Do not generate a session just to make capture succeed. A same-origin backend handling a signed-in guest can instead pass its server-held guest access token as guestAccessToken; the SDK sends it in X-Kismet-Guest-Token, not in JSON or a URL. A guest token takes precedence over a supplied session ID.

For a Next.js backend using Kismet guest authentication, use the SDK’s server-side resolver with your site’s existing consent decision and guest-session secret:

import { resolveKismetSearchCaptureIdentity } from '@kismet-tech/sdk/next';
async function searchWithCapture(request: Request, query: string, consentAllowsTracking: boolean) {
const identity = await resolveKismetSearchCaptureIdentity(request, {
captureAllowed: consentAllowsTracking,
sessionSecret: process.env.KISMET_GUEST_SESSION_SECRET,
production: process.env.NODE_ENV === 'production',
});
return kismet.bookableProduct.search({ query, ...identity });
}

Call this only after validating the request’s exact origin and input. It reads the existing _kid_sid cookie, or a valid unexpired BFF-sealed guest session. It ignores identity in request bodies and query strings, never mints a session, and returns no identity when capture is denied. The API still validates the session’s collection and TEST/LIVE environment. Keep the returned identity on the server; return only the search result to the browser. Continue using your existing telemetry middleware/k.js and save handlers for page views and saves, so every action shares that session rather than starting another event stream.

Search still returns discovery results when no journey can be recorded. Inspect capture separately:

Result Meaning
recorded: true, reason: null The ask was recorded on the guest journey.
no_guest_session No guest session was supplied.
invalid_guest_session The supplied guest identity could not be verified.
no_active_journey There is no eligible active journey for this session.
environment_mismatch TEST capture would attach to live guest activity and was refused.
capture_failed Capture failed; discovery results remain usable.
structured_search No natural-language ask was supplied; no ask was recorded.
continuation_page This page continues an existing search; no duplicate ask was recorded.

TEST asks are sandbox activity and appear only in Developer mode. Capture does not grant marketing consent, enroll a member, or imply a booking. It is also separate from the event ledger and webhook destinations: do not assume every recorded search emits an external webhook.

Test an undated query, a complete date pair, unknown pricing, an empty result, and a response with relaxed matching. Verify request dates/guests, ranking, currency, and fee/tax labels. For capture, check the response and the correct TEST or LIVE journey; a successful HTTP response alone does not prove capture or semantic ranking.

For flexible requests such as “all weekends in July,” consume each hit’s stayOptions rather than treating price.stay as the only available weekend. The API evaluates up to 60 arrival candidates within a 92-day scan; open-length windows evaluate one through seven nights per arrival (up to 420 options). Each option keeps its exact dates, nights, nullable availability and nullable indicative price. Unknown coverage is not unavailable. The legacy price.stay is the first qualifying stay, not the minimum price across weekends.

Show each home once. For a “From” rate, compare only available, priced options with the same currency and stay length. Label the card with the selected price’s exact dates. Carry those dates and all returned options into the detail drawer; changing the selected option must recheck canonical availability before booking. Never infer a price or availability for an option the response did not confirm.