Hunt workflow

Find my best-fit options.

Turn a natural-language query into source-bound candidates ranked by price, eligibility, and evidence — then pause for human selection or hand off to Bridge and Pay.

Try in sandbox View contract

Source-bound discovery

Collect public signals, market results, local places, lead sources, or evidence candidates with source attempts preserved.

Ranked next action

Normalize user constraints such as location, budget, distance, currency, and urgency before ranking options.

Portable proof

Return evidence status, confidence, open questions, and a proof card that can move with the workflow.

Request

Use findBestFit when discovery is the job.

Hunt pauses after finding candidates and returns a NEEDS_INPUT(choice) response. The client selects an item, then resumes with an action of buy or contact.

Full Hunt API reference

Initial request

curl -X POST https://api.patchr.co/v1/orchestrator/run \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -d '{
    "request": "Buy me an iPhone 7 under $550",
    "conversationId": "conv_hunt_1"
  }'

Response — NEEDS_INPUT(choice)

{
  "status": "NEEDS_INPUT",
  "results": {
    "hunt": {
      "inputKind": "choice",
      "reason": "Hunt found 3 option(s). Please select one.",
      "choices": [
        { "candidateId": "...", "title": "Apple iPhone 7 32GB", "netUsd": 499, "source": "blocket" },
        { "candidateId": "...", "title": "iPhone 7 128GB – sealed", "netUsd": 540, "source": "ebay" }
      ]
    }
  }
}

Resume — user selects an item

curl -X POST https://api.patchr.co/v1/orchestrator/run \
  -H "Authorization: Bearer $PATCHR_API_TOKEN" \
  -d '{
    "action": "buy",
    "itemId": "<candidateId>",
    "conversationId": "conv_hunt_1"
  }'