Search the property database by investment criteria (1 credit per result)

POST /api/workspace/search/

1 credit per property

What it returns

The full set of properties matching your investment filters — each with valuation, investment metrics, condition, and location detail. This is the charged database search.

⚠️ Cost — read before calling

1 credit per property returned. A search that matches 1,200 properties costs 1,200 credits. Charging is all-or-nothing: if the balance can't cover the whole set, nothing is charged and the call returns 402.

Always call preview_property_search first, show the user the count and cost, and get an explicit yes before calling this. Never run a broad or location-only search without confirming the cost.

When to use it

After preview_property_search and explicit user confirmation of the credit cost.
To pull a curated, filtered list of investment properties for an area.

Required filters

Same as preview_property_search: a location (city/county/ZIP — NEVER a whole state: state-wide queries time out before returning), a property_status, and at least one investment filter (or allow_location_only=true to waive only the investment filter). Send the SAME filters you previewed so the cost matches.

Pricing

1 credit per matching property, charged all-or-nothing on success. 400/401/402 cost 0 credits.

Responses

200 — The full matching result set. charged credits (= count) were deducted; credits_left is the new balance.
400 — Required filters missing. The missing array lists the unmet obligations. Costs 0 credits.
401 — Authentication failed. Costs 0 credits.
402 — No active subscription, OR insufficient credits for the whole set (nothing was charged — the body carries credits_left and required).