---
title: "Free-text vibe search over property embeddings"
method: GET
path: "/properties/vibe-search"
tags: ["Propertys"]
---

# Free-text vibe search over property embeddings

`GET /properties/vibe-search`

## Request

- Base URL: `http://localhost:8000`
- URL: `http://localhost:8000/properties/vibe-search`
- Auth: none declared

Phase 7 of the semantic-search roadmap: the Hero homepage fallback
for queries that don't route to a place or a structured feature.

The query is normalised and embedded (``text-embedding-3-small``,
Redis-cached for 24 h), then cosine-ranked against
``properties.embedding`` with a permissive similarity floor. The
response shape mirrors ``/categories/{slug}/parks`` and
``/properties/{id}/similar``: a ``SuccessPayload`` whose ``data``
is a list of expanded GeoJSON features.

Fail-open semantics:
* Empty ``q`` → 200 + empty list (not 400, so the frontend can
  safely call this with a loading-state query).
* OpenAI outage → 200 + empty list (service degrades; the Hero
  falls back to rendering the same "no parks match" banner as a
  genuine zero-match result).
* DB vector error → 200 + empty list.

## Query parameters

- `q` string: Free-text vibe query. Empty string returns 200 + empty list (fail-open for misuse).
- `limit` integer: Maximum number of parks to return (1-24). Defaults to 12.
- `country` 'AU' | 'NZ': ISO country code used to scope public property inventory.

## Headers

- `API-Version` '1'

## Response `200`

Successful Response

- SuccessPayload
  - `msg` string, required
  - `data` union
    - object
    - unknown[]
      - unknown
    - string

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/totalparks/apis/total-parks-public-api.md) · [All operations](https://skmtc.dev/totalparks/apis/total-parks-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/totalparks/apis/total-parks-public-api/revisions/dcb4c822e2c6?raw)