Find bookable appointment slots

Granted location + visit reason + time window -> ranked slots with opaque
slot tokens. Soft failures return { ok: false, reason:, message: } rather than
HTTP errors - message is always present and safe to relay to the caller as-is.

Example request

curl -X POST https://nexhealth.info/intent/booking/search \
  -H 'Authorization: Bearer <token>' -H 'Content-Type: application/json' \
  -d '{
    "location_id": 42,
    "visit_reason": "cleaning",
    "when": { "earliest_date": "2026-08-10", "days": 7, "parts_of_day": ["morning"] },
    "limit": 5
  }'

Example success response

{ "ok": true,
  "slots": [
    { "slot_token": "slt_9f2c1b7e4a5d6c8b9f2c1b7e4a5d6c8b",
      "start_local": "Mon, Aug 10 · 9:00 AM PDT",
      "start_iso": "2026-08-10T09:00:00-07:00",
      "duration_minutes": 30,
      "provider": "Dr. Sarah Johnson",
      "location": { "location_id": 42, "name": "Main St Dental", "address": "1 Main St, Seattle, WA, 98101" } }
  ],
  "summary": { "searched_locations": 1, "with_availability": 1, "window_days": 7 } }

Reason catalog (branch on reason when ok is false)