---
title: "Search published bookable products with natural language"
description: "Runs a collection-scoped semantic search over published bookable products. Results are ranked discovery candidates, not availability claims, stay quotes, or booking offers. The first release keeps the evidence gate off so each request consumes one bounded quota unit."
---

`POST /v1/developer/collections/{collection}/search`

**Operation ID:** `searchBookableProducts`

Runs a collection-scoped semantic search over published bookable products. Results are ranked discovery candidates, not availability claims, stay quotes, or booking offers. The first release keeps the evidence gate off so each request consumes one bounded quota unit.

## Contract status

| Field | Value |
| --- | --- |
| Maturity | `beta` |
| Required capability | `search.read` |
| Freshness class | `published-content` |
| Quota cost | `1` |
| Operational owner | Search + API + Developer Experience |

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

| Name | In | Type | Required | Description |
| --- | --- | --- | --- | --- |
| `collection` | path | string | yes |  |

## Request body

The request body is JSON. The canonical schema is:

```json
{
  "type": "object",
  "additionalProperties": false,
  "required": [
    "query"
  ],
  "properties": {
    "query": {
      "type": "string",
      "minLength": 2,
      "maxLength": 500
    },
    "topK": {
      "type": "integer",
      "minimum": 1,
      "maximum": 24,
      "default": 12
    }
  }
}
```

Minimal example:

```json
{
  "query": "string"
}
```

## cURL

```sh
curl --request POST \
  "$KISMET_API_ORIGIN/v1/developer/collections/sand-sea-condos/search" \
  --header "Authorization: Bearer $KISMET_DEVELOPER_API_KEY" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"query":"string"}'
```

## 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. |

### Success example

```json
{
  "ok": true,
  "query": "a quiet beach stay for eight with a pool",
  "intent": {},
  "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,
  "verifiedFits": 3,
  "candidates": 5,
  "matchedCount": 3,
  "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
      },
      "score": 8.7,
      "reason": "Fits the requested capacity and pool preference.",
      "verifiedFeatures": [
        "pool"
      ],
      "typeMatch": true,
      "matched": true,
      "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
    }
  }
}
```

## Machine-readable sources

- [This page as Markdown](/api/reference/search-bookable-products.md)
- [Developer API OpenAPI v0.7.2](/openapi.json)