AAppoint Dr Watson Suite

Tier C, WRITE, irreversible. Cancel a booking (POST /bookings/{eventid}/cancel). eventid is PATH parameter; access_token maps to Authorization header. Body is literal {} (body-less -> 411). Free-booking cancel -> 200 with NO refund_note. Paid-deposit cancel -> 200 WITH a refund_note (deposit not auto-refunded; user contacts AAppoint). Another user's booking -> 404.

Tier C, WRITE. Leave the queue (POST /waitlist/entries/{entry_id}/cancel). entry_id is a STRING (uuid) PATH parameter; access_token maps to Authorization header. Body literal {}. Idempotent. A SEATED entry -> 409 already-seated. Another user's entry -> 404.

Tier C. Live slot availability (GET /restaurants/{shop_id}/availability). shop_id is a PATH parameter; service_id, party_size, start_date, end_date are query. end_date required by this schema, must be at or after start_date (inverted -> 400 invalid-date-range). access_token maps to Authorization header. Returns {available_slots:[{date, slots:[{start_sec, duration_sec, available_zones:[{zone_id, zone_name, available_seats, service_id}]}]}]}. party_size does NOT filter zones server-side: keep only zones where available_seats >= party_size before presenting. Copy slots[].start_sec verbatim into AAppoint_CreateBooking; render times in the venue timezone.

Tier C, WRITE. Books a real table (POST /bookings). access_token in Authorization header; idempotency_key, shop_id, service_id, party_size, start_sec, customer in body. Contact MUST nest under customer (flat leads to 400). NEVER send zone_id/zone_name (leads to 409 slot-unavailable; server auto-selects). Numbers unquoted, customer object unquoted, strings quoted. Returns nested under booking + deposit. Read booking.id as eventid. deposit.required false leads to confirmed immediately, skip checkout. Malformed contact leads to 500 customer-create-failed: normalize phone/email, retry reusing the same idempotency_key.

Tier C. Poll booking status (GET /bookings/{eventid}). eventid is PATH parameter; access_token maps to Authorization header. Returns wrapped under booking: {booking:{id, status, start_sec, ...}}. Only status=confirmed proves the table is held. Also the cancel-flow ownership check: 200 = this user's booking (isolation: the access token IS the identity); 404 = not this user's booking.

Tier C. Restaurant detail (GET /restaurants/{shop_id}). shop_id is a PATH parameter; access_token maps to Authorization header. Returns wrapped under restaurant: {restaurant:{id, accepting_new_bookings, waitlist_status, timezone, latitude, longitude, google_map_url, payment_policy, city}}. The ONLY place accepting_new_bookings and waitlist_status appear; require accepting_new_bookings=true for auto-book. No structured deposit here (only prose payment_policy); deposit comes from AAppoint_ListServices. waitlist_status is OPEN / CLOSED_NO_WAIT / CLOSED_OTHER.

Tier C. Poll queue position (GET /waitlist/entries/{entry_id}). entry_id is a STRING (uuid) PATH parameter; access_token maps to Authorization header. Returns wrapped under waitlist_entry: {waitlist_entry:{state: CREATED|SEATED|CANCELED|ABANDONED, parties_ahead, ...}}. parties_ahead 0 = next. Stuck CREATED for 12h -> ABANDONED. Never claim ready without a live SEATED this turn.

Tier C. Waitlist availability (GET /restaurants/{shop_id}/waitlist). shop_id is PATH; optional service_id is query. access_token maps to Authorization header. Returns {waitlist_status: OPEN|CLOSED_NO_WAIT|CLOSED_OTHER, min_party_size, max_party_size, parties_waiting}.

Tier C, WRITE. Join a walk-in queue (POST /waitlist/entries). access_token in Authorization header; idempotency_key, shop_id, service_id, party_size, customer in body. party_size 1-10. Contact nested under customer (first_name + phone minimum). Returns wrapped under waitlist_entry. Errors: 400 waitlist-closed / waitlist-no-wait / waitlist-full / waitlist-invalid-party-size; 404 service-not-found.

Tier C. Lists bookable services for a restaurant (GET /restaurants/{shop_id}/services). shop_id is a PATH parameter; access_token maps to Authorization header. Returns wrapped under services: {services:[{id, pricing_model, deposit, duration_sec, products:[{id, pricing_model, deposit}]}, ...]}. services[].id = service_id. deposit is a STRING THB amount ('0'/'30'/'50'/'100'). pricing_model per_head -> total = deposit x party_size; per_table -> deposit as-is. ALWAYS use the service-level deposit, never products[].deposit (a placeholder that can mismatch). '0' = free.

Tier C. Lists bookable service-type slugs for the geo/category search filter (GET /service-types). access_token maps to Authorization: Bearer header. Returns {service_types:[{id, name_en, name_th}, ...]}. Use `id` (e.g. 'restaurant') as the service_type filter on AAppoint_SearchRestaurants.

Tier B (no auth, DIFFERENT HOST, corrected). Static public ShopeePay Coin Cashback feed (GET https://shopeepay.marketplace.aappoint.me/shops.json). Headers carry Accept but NOT Authorization; the non-empty headers field suppresses the partner-secret injection, so this separate marketplace host receives no auth. No token attached. Returns {shops:[{id, name, link, bookable, comingSoon, ...}]}. shops[].id is a SEPARATE id space from Partner API shop_id (never cross them); use shops[].link verbatim; skip comingSoon/not-bookable entries.

Tier B (no auth, corrected). Exchanges the stored refresh token for a fresh access token via POST /token. Headers carry Content-Type but NOT Authorization; the non-empty headers field suppresses the partner-secret injection, so the call carries no Authorization header and authenticates on the body refresh token alone. Call on 401 unauthorized or when the access token is older than ~1h. On 401 invalid_grant the refresh token is dead - re-register via AAppoint_RegisterUser.

Tier A. Mints this user's per-user token pair against /register. external_user_id = the Steward's humanId (steward.partyId from REGISTRY cycle context, stable per person across all their Minds). Idempotent on external_user_id: re-registering returns the SAME agent_user_id with new tokens (booking history preserved across Minds). PARTNER_SECRET is injected by the platform as Authorization: Bearer (providerKey=aappoint, header_key=Authorization, value_prefix='Bearer '). No tool-level headers field. Returns {agent_user_id, token_type, access_token (agta_...), expires_in, refresh_token (agtr_...)}. Tokens are SECRETS - store in TENET aappoint_session only, never echo, never LTM.

Tier C. Two-mode restaurant search (GET /restaurants). `q` matches a name; `service_type`+`latitude`+`longitude`+`radius_km` does nearest-first geo/category discovery. `city` is an opaque exact-match token (prefer lat/lng). access_token maps to Authorization header. Returns wrapped under restaurants: {total, limit, offset, restaurants:[{id, name_en, name_th, service_type, city, latitude, longitude, address, distance_meters?}, ...]}. Read restaurants[].id as shop_id. latitude/longitude are STRINGS; distance_meters is a float and appears only on geo queries.

Tier C, WRITE (commits a payment). Drives a deposit checkout (POST /bookings/{eventid}/deposit/checkout). eventid is PATH parameter; access_token maps to Authorization header; payment_method and result_url in body. payment_method from deposit.payment_options.gateways (promptpay/shopeepay/alipay). result_url = https://hellomind.ai/return on every method. Returns {payment_method, checkout_url, payment_uri, amount, payment_expire_at, booking_id}. Quote `amount` (gateway total; promptpay adds ~1 THB) as the sum due, never the services deposit. 30-min hold. 502 -> offer a different method. Switching method: POST again on same eventid (invalidates prior link).

Tier C. Optional sanity check that the stored access token is valid (GET /me). access_token maps to Authorization: Bearer header via headersParameters. Returns {agent_user_id, status, external_user_id, created_at}.