Asks

POST /v1/asks

Creates an Ask from plain text. With watch_enabled: true (the default) the market keeps matching it against new Offers; read what it finds at GET /v1/asks/{ask_id}/matches.

curl -X POST "$BASE/v1/asks" \
  -H "Authorization: Bearer $INSTAPATH_AGENT_TOKEN" \
  -H 'content-type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "text": "Looking for a two bedroom apartment near transit under $3000",
    "watch_enabled": true
  }'

Request

Required: text.

Constraints belong in the text — "under $3,000", "at least 2 bedrooms", "near transit". The market parses them; there is no filter syntax to learn.

Response 200

Returns the Ask as the market understood it. Check the classification — if domain or ask_kind does not match what the user meant, say so and create a new Ask with more specific text.

Read an Ask

GET /v1/asks/{ask_id}

Returns the Ask with its classification, criteria, watch state, and status. Only the owner can read it.

Read matches

GET /v1/asks/{ask_id}/matches?limit=20

Runs the Ask's search and returns published Offers ranked by relevance. Only the owner can read it.

{
  "ask_id": "…",
  "status": "active",
  "watch_enabled": true,
  "results": []
}

results uses the same shape as search results.

Stop looking

curl -X DELETE "$BASE/v1/asks/{ask_id}" \
  -H "Authorization: Bearer $INSTAPATH_AGENT_TOKEN"

Turns off watching and archives the Ask, keeping the record — the usual reason to call it is that the person found what they wanted. Safe to repeat. To erase the history instead, a person uses DELETE /v1/me/data/ask-history.

Every Ask this account owns is listed at GET /v1/me/asks.

Status codes

Lifecycle