Search published bookable products with optional natural language
View .mdPOST /v1/developer/collections/{collection}/search
Operation ID: searchBookableProducts
Search published bookable products within the authorized collection. Omit query for structured browsing with no AI calls; supply query for semantic ranking. Use limit (1–50) and cursor for a five-minute stable result set. Repeat the same parameters on subsequent pages; INVALID_CURSOR means restart. Explicit group, building, minimum bedrooms/bathrooms, petsAllowed, dates and guests are authoritative. Availability and canonical before-tax pricing are applied before pagination; available:null means unknown, not sold out. page.total counts this result set, not the whole catalog; semantic recall is bounded and is not exhaustive inventory. Narrow collections over 1000 eligible products with a group or building. Existing query/topK-only calls retain their legacy bounded response. Results are discovery candidates, not binding quotes or booking offers. A collection can feature (pin) chosen products: on the recommended sort they lead the result set in the order the collection set, after every filter, and each hit carries featured:true so a card can badge it; on a dated search a featured product that is not bookable for the dates is dropped like any other unavailable product, never lifted above bookable ones; explicit sorts and semantic relevance keep their own order and still carry the marker. Changing the featured set invalidates open cursors (INVALID_CURSOR). Optional checkIn, checkOut and guests come from your own form and override what the query text implies; with dates, each hit carries the full before-tax stay price next to its 90-day nightlyFrom: accommodation, cleaning and required fees folded in and divided across nights, the same display convention as getCollectionAvailability and checkout, so a card never shows a number the guest will not see at the next step. With no dates from your form, the stays the query itself names are checked: a date pair prices each hit as price.stay, and two or three alternative stays (“the weekend of Dec 4 or the one after”) are judged like dateRanges, each hit carrying every option on stayOptions and availability.alternatives counting the hits free for each. Flexible windows (for example all weekends in July) return every evaluated candidate in stayOptions, including unavailable and unknown options, within the existing 60-arrival/92-day bound (up to 420 stays when length is flexible). A home qualifies if at least one option is available; unknown coverage stays unknown. price.stay retains the first qualifying stay for compatibility and is not the minimum across options. Compare only available, priced options of equal duration and currency when displaying a From rate, and carry the selected option dates into a fresh availability check before booking. availability.checked says whether any dates were checked. Taxes are revealed at checkout. Price is never a quote; use the quote operations to charge. Asks reach the guest journey: send the guest session (an X-Kismet-Guest-Token bearer for a signed-in guest, or guestSessionId, the kid_ session id the browser client holds) and the ask is recorded on that journey and the collection pipeline, exactly like an ask from the drop-in loader, with its own nl_ask event so the journey shows each call separately. TEST installations record sandbox asks that appear only in developer mode; a TEST ask on a session with live activity is refused (capture.reason environment_mismatch), so test traffic never lands on a real guest. No session, no write; the search still answers, and capture.reason says why.
Contract status
Section titled “Contract status”| Field | Value |
|---|---|
| Maturity | beta |
| Required capability | search.read |
| Freshness class | published-content |
| Quota cost | 1 |
All operations require a Kismet Developer Bearer credential. Collection and resource authority is resolved from the credential’s installation grants; identifiers in the URL never grant access.
Request parameters
Section titled “Request parameters”| Name | In | Type | Required | Description |
|---|---|---|---|---|
collection |
path | string | yes | |
x-kismet-guest-token |
header | string | no | Optional BFF-held guest access token for journey capture. Takes precedence over guestSessionId; an invalid guest token prevents capture without failing discovery. |
Request body
Section titled “Request body”The request body is JSON. The canonical schema is:
{ "type": "object", "additionalProperties": false, "properties": { "query": { "type": "string", "minLength": 2, "maxLength": 500 }, "intent": { "type": "object", "properties": { "checkIn": { "type": [ "string", "null" ] }, "checkOut": { "type": [ "string", "null" ] }, "guests": { "type": [ "number", "null" ] }, "bedrooms": { "type": [ "number", "null" ] }, "petsRequired": { "type": [ "boolean", "null" ] }, "budgetMaxPerNight": { "type": [ "number", "null" ] }, "budget": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000 }, "basis": { "type": "string", "enum": [ "nightly", "total" ] }, "firmness": { "type": "string", "enum": [ "firm", "flexible" ] }, "currency": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{3}$" }, { "type": "null" } ] } }, "required": [ "amount", "basis", "firmness", "currency" ], "additionalProperties": false }, { "type": "null" } ] }, "locality": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "propertyTypes": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "features": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "personas": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "residue": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "wants": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string" }, "strength": { "type": "string", "enum": [ "required", "preferred" ] } }, "required": [ "feature", "strength" ], "additionalProperties": false } }, { "type": "null" } ] }, "dateWindow": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "weekend", "long_weekend", "week", "month", "range" ] }, "earliest": { "type": "string" }, "latest": { "type": "string" }, "nights": { "type": [ "number", "null" ] }, "startDow": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] } }, "required": [ "kind", "earliest", "latest" ], "additionalProperties": false }, { "type": "null" } ] }, "places": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "kind": { "type": "string", "enum": [ "town", "region", "nearby" ] } }, "required": [ "text", "kind" ], "additionalProperties": false } }, { "type": "null" } ] }, "dateAlternatives": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "checkIn": { "type": "string" }, "checkOut": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "checkIn", "checkOut" ], "additionalProperties": false } }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Structured intent to re-run, including a returned broadening. Requires query; cannot be combined with previousIntent. Filters only narrow the authorized catalog." }, "previousIntent": { "type": "object", "properties": { "checkIn": { "type": [ "string", "null" ] }, "checkOut": { "type": [ "string", "null" ] }, "guests": { "type": [ "number", "null" ] }, "bedrooms": { "type": [ "number", "null" ] }, "petsRequired": { "type": [ "boolean", "null" ] }, "budgetMaxPerNight": { "type": [ "number", "null" ] }, "budget": { "anyOf": [ { "type": "object", "properties": { "amount": { "type": "number", "exclusiveMinimum": 0, "maximum": 1000000 }, "basis": { "type": "string", "enum": [ "nightly", "total" ] }, "firmness": { "type": "string", "enum": [ "firm", "flexible" ] }, "currency": { "anyOf": [ { "type": "string", "pattern": "^[A-Z]{3}$" }, { "type": "null" } ] } }, "required": [ "amount", "basis", "firmness", "currency" ], "additionalProperties": false }, { "type": "null" } ] }, "locality": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "region": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "propertyTypes": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "features": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "personas": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "residue": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "wants": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "feature": { "type": "string" }, "strength": { "type": "string", "enum": [ "required", "preferred" ] } }, "required": [ "feature", "strength" ], "additionalProperties": false } }, { "type": "null" } ] }, "dateWindow": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "weekend", "long_weekend", "week", "month", "range" ] }, "earliest": { "type": "string" }, "latest": { "type": "string" }, "nights": { "type": [ "number", "null" ] }, "startDow": { "type": [ "string", "null" ] }, "label": { "type": [ "string", "null" ] } }, "required": [ "kind", "earliest", "latest" ], "additionalProperties": false }, { "type": "null" } ] }, "places": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "text": { "type": "string" }, "kind": { "type": "string", "enum": [ "town", "region", "nearby" ] } }, "required": [ "text", "kind" ], "additionalProperties": false } }, { "type": "null" } ] }, "dateAlternatives": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "checkIn": { "type": "string" }, "checkOut": { "type": "string" }, "label": { "type": [ "string", "null" ] } }, "required": [ "checkIn", "checkOut" ], "additionalProperties": false } }, { "type": "null" } ] } }, "additionalProperties": false, "description": "Previous response intent for a natural-language follow-up. query contains only the new instruction. Omit for a fresh search. Repeat unchanged with cursor." }, "topK": { "type": "integer", "minimum": 1, "maximum": 24 }, "limit": { "type": "integer", "minimum": 1, "maximum": 50 }, "cursor": { "type": "string", "minLength": 1, "maxLength": 100 }, "sort": { "enum": [ "relevance", "recommended", "name-asc", "bedrooms", "sleeps" ] }, "group": { "type": "string", "minLength": 1, "maxLength": 200 }, "building": { "type": "string", "minLength": 1, "maxLength": 200 }, "minBedrooms": { "type": "integer", "minimum": 0, "maximum": 100 }, "minBathrooms": { "type": "number", "minimum": 0, "maximum": 100 }, "petsAllowed": { "type": "boolean" }, "dateRanges": { "description": "One to three explicit alternative stays (1–90 nights, up to 16 guests). Cannot be combined with checkIn/checkOut. A product qualifies for any available range; unknown inventory remains unknown. Union and deduplication happen before pagination. Repeat ranges with the cursor; changing them requires a new search. Omitted, with no checkIn/checkOut, the alternative stays the query itself names are checked the same way.", "type": "array", "minItems": 1, "maxItems": 3, "items": { "type": "object", "additionalProperties": false, "required": [ "checkIn", "checkOut" ], "properties": { "checkIn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "checkOut": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" } } } }, "checkIn": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "checkOut": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "guests": { "type": "integer", "minimum": 1, "maximum": 100 }, "guestSessionId": { "type": "string", "pattern": "^kid_[A-Za-z0-9]{8}$" } }}Minimal example:
{}Set KISMET_API_ORIGIN=https://api.ksmt.app and configure KISMET_DEVELOPER_API_KEY in your environment. Run server-credential requests from your backend, not browser code.
Guest access tokens come from the signed-in guest session held by your backend. Forward a CSRF proof only after your same-origin backend validates it. If shown, KISMET_SITE_ORIGIN is the authorized origin of your site. Do not substitute a guest ID or an invented token.
curl --request POST \ "$KISMET_API_ORIGIN/v1/developer/collections/example-collection/search" \ --header "Authorization: Bearer $KISMET_DEVELOPER_API_KEY" \ --header "Accept: application/json" \ --header "Content-Type: application/json" \ --data '{}'Responses
Section titled “Responses”| Status | Meaning |
|---|---|
| 200 | Success. |
| 400 | Invalid request parameters or body. |
| 401 | Missing, invalid, expired, or inappropriate credential/session. |
| 403 | Credential lacks the required grant/capability, or an origin/CSRF check failed. |
| 404 | The authorized resource was not found. |
| 429 | Rate limit or quota exceeded; inspect response metadata before retrying. |
| 503 | A required Kismet dependency is temporarily unavailable. |
200 response example
Section titled “200 response example”{ "ok": true, "query": "a quiet beach stay for eight with a pool", "intent": { "checkIn": "2026-10-09", "checkOut": "2026-10-12", "guests": 8 }, "chips": [], "remainder": "quiet beach stay", "pool": 5, "poolBeforeGraph": 12, "availability": { "checked": false, "nights": 0, "poolBeforeAvailability": 5, "unknown": 0 }, "graphFilters": [], "graphRelaxed": false, "reviewSuppressed": 0, "localityRelaxed": false, "broadenings": [], "typeUnanswerable": [], "placeResolution": [], "verifiedFits": 3, "candidates": 5, "matchedCount": 3, "capture": { "recorded": true, "reason": null }, "ranked": [ { "resourceType": "bookable_product_search_hit", "type": "vacation_rental", "product": { "slug": "sandbox-beach-house", "name": "Sandbox Beach House", "heroImageUrl": "https://cdn.kismet.travel/sandbox/beach-house.jpg", "servingUrl": "https://sandbox-stays.example/stays/sandbox-beach-house", "maxGuests": 8, "bedrooms": 4, "bathrooms": 3, "location": { "locality": "Sandbox Beach", "region": "CA" }, "homeCollection": { "slug": "sandbox-stays", "name": "Sandbox Stays" } }, "price": { "nightlyFrom": { "amountMinor": 42000, "currency": "USD", "horizonDays": 90 }, "stay": { "checkIn": "2026-10-09", "checkOut": "2026-10-12", "nights": 3, "nightlyMinor": 52500, "totalBeforeTaxMinor": 157500, "currency": "USD", "source": "ask" } }, "score": 8.7, "reason": "Fits the requested capacity and pool preference.", "verifiedFeatures": [ "pool" ], "typeMatch": true, "matched": true, "preferredMatches": [], "evidence": null } ], "meta": { "snapshotMs": 4, "parseMs": 80, "recallMs": 24, "gateMs": 0, "totalMs": 108, "source": "developer-api", "recallLeg": "hybrid", "gateLeg": "off", "gate": { "inputTokens": 0, "outputTokens": 0, "estCostUsd": null } }}200 response schema
Section titled “200 response schema”Content type: application/json. Required fields, nullable values, and nested structures are defined below.
View complete response schema
{ "type": "object", "additionalProperties": false, "required": [ "ok", "query", "intent", "chips", "remainder", "pool", "poolBeforeGraph", "availability", "graphFilters", "graphRelaxed", "reviewSuppressed", "localityRelaxed", "verifiedFits", "candidates", "matchedCount", "capture", "ranked", "meta" ], "properties": { "ok": { "enum": [ true ] }, "mode": { "enum": [ "structured", "semantic" ] }, "page": { "type": "object", "additionalProperties": false, "required": [ "limit", "nextCursor", "total", "expiresAt" ], "properties": { "limit": { "type": "integer" }, "nextCursor": { "type": [ "null", "string" ] }, "total": { "type": "integer" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "capture": { "type": "object", "additionalProperties": false, "required": [ "recorded", "reason" ], "properties": { "recorded": { "type": "boolean" }, "reason": { "type": [ "null", "string" ], "enum": [ "no_guest_session", "invalid_guest_session", "no_active_journey", "environment_mismatch", "capture_failed", "structured_search", "continuation_page", null ] } } }, "query": { "type": "string" }, "intent": { "type": "object", "additionalProperties": true }, "chips": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "remainder": { "type": [ "null", "string" ] }, "pool": { "type": "integer" }, "poolBeforeGraph": { "type": "integer" }, "availability": { "type": "object", "additionalProperties": true }, "graphFilters": { "type": "array", "items": { "type": "object", "additionalProperties": true } }, "graphRelaxed": { "enum": [ false ] }, "reviewSuppressed": { "type": "integer" }, "localityRelaxed": { "enum": [ false, "region", "dropped" ] }, "verifiedFits": { "type": "integer" }, "candidates": { "type": "integer" }, "matchedCount": { "type": [ "null", "integer" ] }, "amended": { "description": "With previousIntent: true when the query amended it (the parser kept what you did not change), false when it started over for an unrelated query. Absent for a fresh search. The recorded ask carries it, so a thread of asks is queryable.", "type": "boolean" }, "note": { "type": "string" }, "ranked": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "resourceType", "type", "product", "score", "reason", "verifiedFeatures", "typeMatch", "matched", "evidence", "price" ], "properties": { "resourceType": { "enum": [ "bookable_product_search_hit" ] }, "available": { "type": [ "null", "boolean" ] }, "budgetStatus": { "enum": [ "within", "over", "unknown" ] }, "stayOptions": { "description": "The stays checked for this hit: every bounded candidate in a flexible date window, your dateRanges, or, when you sent no dates, the two or three stays the query itself named (\"the weekend of Dec 4 or the one after\"), in that order. Evaluated against synced inventory; checkedAt is evaluation time, not supplier quote freshness. Unknown/unavailable options have null price. For explicit alternatives price.stay is null; flexible windows retain the first qualifying price.stay for compatibility. stayOptions contains all evaluated candidates (up to 420), not only the first qualifying stay; choose an option and obtain a fresh quote before booking.", "type": "array", "maxItems": 420, "items": { "type": "object", "additionalProperties": false, "required": [ "checkIn", "checkOut", "nights", "available", "checkedAt", "price" ], "properties": { "checkIn": { "type": "string" }, "checkOut": { "type": "string" }, "nights": { "type": "integer" }, "available": { "type": [ "null", "boolean" ] }, "budgetStatus": { "enum": [ "within", "over", "unknown" ] }, "checkedAt": { "type": "string" }, "price": { "type": [ "null", "object" ], "additionalProperties": false, "required": [ "checkIn", "checkOut", "nights", "nightlyMinor", "totalBeforeTaxMinor", "currency" ], "properties": { "checkIn": { "type": "string" }, "checkOut": { "type": "string" }, "nights": { "type": "integer" }, "nightlyMinor": { "type": "integer" }, "totalBeforeTaxMinor": { "type": "integer" }, "currency": { "type": "string" }, "source": { "description": "'ask' when the caller named these dates; 'window' when they are the home's first bookable stay inside a flexible window the ask named (a weekend in November), not dates the caller chose.", "enum": [ "ask", "window" ] } } } } } }, "featured": { "type": "boolean" }, "type": { "enum": [ "vacation_rental" ] }, "product": { "type": "object", "additionalProperties": false, "required": [ "slug", "name", "heroImageUrl", "servingUrl", "maxGuests", "bedrooms", "bathrooms", "location", "homeCollection" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" }, "heroImageUrl": { "type": [ "null", "string" ] }, "servingUrl": { "type": [ "null", "string" ] }, "maxGuests": { "type": [ "null", "integer" ] }, "bedrooms": { "type": [ "null", "integer" ] }, "bathrooms": { "type": [ "null", "number" ] }, "location": { "type": "object", "additionalProperties": false, "required": [ "locality", "region" ], "properties": { "locality": { "type": [ "null", "string" ] }, "region": { "type": [ "null", "string" ] } } }, "homeCollection": { "type": [ "null", "object" ], "additionalProperties": false, "required": [ "slug", "name" ], "properties": { "slug": { "type": "string" }, "name": { "type": "string" } } } } }, "price": { "type": "object", "additionalProperties": false, "required": [ "nightlyFrom", "stay" ], "properties": { "nightlyFrom": { "type": [ "null", "object" ], "additionalProperties": false, "required": [ "amountMinor", "currency", "horizonDays" ], "properties": { "amountMinor": { "type": "integer" }, "currency": { "type": "string" }, "horizonDays": { "type": "integer" } } }, "stay": { "type": [ "null", "object" ], "additionalProperties": false, "required": [ "checkIn", "checkOut", "nights", "nightlyMinor", "totalBeforeTaxMinor", "currency" ], "properties": { "checkIn": { "type": "string" }, "checkOut": { "type": "string" }, "nights": { "type": "integer" }, "nightlyMinor": { "type": "integer" }, "totalBeforeTaxMinor": { "type": "integer" }, "currency": { "type": "string" }, "source": { "description": "'ask' when the caller named these dates; 'window' when they are the home's first bookable stay inside a flexible window the ask named (a weekend in November), not dates the caller chose.", "enum": [ "ask", "window" ] } } } } }, "score": { "type": "number" }, "reason": { "type": "string" }, "verifiedFeatures": { "type": "array", "items": { "type": "string" } }, "typeMatch": { "type": "boolean" }, "matched": { "type": [ "null", "boolean" ] }, "preferredMatches": { "description": "The guest's preferred (hedged) wants this hit covers, by graph fact or its own evidence text. Preferred wants never gate `matched`; they rank and badge.", "type": "array", "items": { "type": "string" } }, "evidence": { "type": [ "null", "object" ], "additionalProperties": false, "required": [ "chunkId", "kind", "text", "photoUrl", "galleryIndex", "featureRelevant", "review" ], "properties": { "chunkId": { "type": "string" }, "kind": { "type": "string" }, "text": { "type": "string" }, "photoUrl": { "type": [ "null", "string" ] }, "galleryIndex": { "type": [ "null", "integer" ] }, "featureRelevant": { "type": "boolean" }, "review": { "type": [ "null", "object" ], "additionalProperties": true } } } } } }, "meta": { "type": "object", "additionalProperties": true } }}