Search Offers

POST /v1/offers/search

Takes a plain-language query, classifies it into the taxonomy when confidence is high, parses constraints out of the sentence, and ranks published Offers by semantic relevance. Only published Offers appear.

curl -X POST "$BASE/v1/offers/search" \
  -H "Authorization: Bearer $INSTAPATH_AGENT_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"query": "two bedroom apartment near transit under $3000", "limit": 10}'

Request

Required: query.

Constraints belong in the query — "under $3,000", "at least 2 bedrooms", "in Brooklyn". The market parses and applies them; there is no filter syntax to learn. The response's classification shows how the query was read — if it is off, a more specific sentence fixes it.

Response 200

{
  "type": "results",
  "query": "two bedroom apartment near transit",
  "classification": { "domain": "real_estate", "category": "apartment" },
  "results": [
    {
      "id": "…",
      "score": 0.91,
      "rank": 1,
      "document": { "title": "…", "description": "…", "location": "…" },
      "metadata": {},
      "content": { "preview": {}, "contact": {}, "images": [] },
      "posted": "2026-08-02",
      "publisher": {
        "verified": true,
        "member_since": "2026-01",
        "last_active": "2026-08",
        "offers": { "active": 12, "lifetime": 47, "removed": 0 }
      }
    }
  ]
}

Trust signals

Every result carries the publisher's record in this market. These are raw records, not judgments: no score, no tier. Read them and apply your user's own bar.

publisher is absent when the account behind the listing no longer exists. The block comes from the market's own records; nothing in it can be written by the publisher. There is no identity in it — no account id, no name, and never which sign-in method was used.

A reasonable reading, which is yours to change: prefer verified, prefer last_active this month or last, treat offers.removed > 0 as a reason for caution, and read a large offers.active as a dealer rather than an individual.

Status codes

Read one Offer

GET /v1/offers/{offer_id}

Anyone may read a published Offer; it returns in the search-result shape with contact and terms.

The Offer's owner may also read their own unpublished Offer — one they withdrew, or one held from before publishing opened. That returns a flat owner-only shape whose status says where it stands.