--- name: resy-booking description: >- Book restaurant reservations on Resy. Use when the user asks to book a table, make a reservation, find a restaurant, or check availability. homepage: https://www.agentres.dev metadata: version: 1 --- # Resy Booking Search for restaurants, check availability, and book reservations on Resy. ## Authentication All endpoints except `/api/search` return **402** when called without auth. The 402 response includes both: - `WWW-Authenticate: Payment ...` — MPP challenge (Tempo wallet) - `PAYMENT-REQUIRED: ` — x402 payment requirements (Base wallet) Your client handles the 402 automatically. If you're using `mppx`, AgentCash, or `@x402/fetch`, auth is transparent. All endpoints are **free** (zero-dollar identity challenge) except `POST /api/book` which costs **0.10 USDC**. For full endpoint details, request/response schemas, and error codes, see the [API Reference](https://www.agentres.dev/api-reference.md). ## Error Handling All error responses include these fields: ```json { "error": { "code": "ERROR_CODE", "message": "Human-readable description", "retryable": false, "next_step": "Specific instruction on what to do next" } } ``` **Always check the `next_step` field** when you get an error — it tells you exactly how to recover. ## Workflow Follow these steps in order. Each step tells you exactly what to ask the user and what API call to make. ### Step 1: Check existing setup Before anything else, check if the user already has an account: ``` GET https://www.agentres.dev/api/me ``` - If you get a **200** with `resy_linked: true` → skip to **Step 4** (search). - If you get a **200** with `resy_linked: false` → skip to **Step 3** (link Resy). - If you get a **401** (wallet not linked) → continue to **Step 2** (create account). ### Step 2: Create account Ask the user: **"What email would you like to use for your account?"** ``` POST https://www.agentres.dev/api/account Content-Type: application/json {"email": ""} ``` Your wallet is automatically linked to the account. If the account already exists, you'll get a 200 instead of 201 — that's fine, continue. ### Step 3: Link Resy account Ask the user: **"What email is your Resy account under? It may be the same email or a different one."** Request the OTP: ``` POST https://www.agentres.dev/api/link-resy Content-Type: application/json {"em_address": ""} ``` Tell the user: **"I've sent a verification code to your email. What's the 6-digit code?"** Once they provide it, verify: ``` POST https://www.agentres.dev/api/link-resy Content-Type: application/json {"em_address": "", "code": ""} ``` The code can be `123456` or `123-456` — both formats work. ### Step 4: Search for a restaurant Ask the user: **"What restaurant are you looking for?"** Search Resy with their query: ``` GET https://www.agentres.dev/api/search?query= ``` This returns up to 5 matches with venue IDs, names, neighborhoods, cuisine types, and ratings. Present the results to the user in a readable format, like: > 1. **Cafe China** — Midtown, Chinese — Rating: 4.8 (venue ID: 59237) > 2. **China Blue** — Tribeca, Chinese — Rating: 4.5 (venue ID: 12345) Ask the user: **"Which one would you like to book?"** Remember the `venue_id` of their choice — you'll need it for the next steps. If none of the results match, ask the user to try a different search term and repeat this step. ### Step 5: Get availability Ask the user: **"What date would you like? And how many people?"** Fetch available time slots: ``` GET https://www.agentres.dev/api/availability?venue_id=&party_size=&day= ``` The response includes `venue_name` so you can display it. Present the available slots clearly: > Available times at **Cafe China** on Apr 15, 2026 for 2 people: > > 1. Dining Room — 5:30 PM > 2. Dining Room — 7:00 PM > 3. Dining Room — 7:30 PM > 4. Bar — 8:00 PM > 5. Bar — 9:30 PM Ask the user: **"Which time slot would you like to book?"** Remember the `config_id` of the slot they choose. If no slots are available, suggest trying a different date or party size. ### Step 6: Book the reservation Once the user picks a slot, book it: ``` POST https://www.agentres.dev/api/book Content-Type: application/json { "venue_id": "", "config_id": "", "party_size": , "day": "" } ``` This costs **0.10 USDC**. On success, confirm to the user: > **Reservation confirmed!** You're booked at Cafe China on Apr 15, 2026 at 7:30 PM for 2 people. Your confirmation ID is 123456. If you get a 409 (already booked), tell the user they already have a reservation at that restaurant. ## Rules 1. **Check /api/me first** — skip setup steps if the user is already linked. 2. **Always search first** — use `/api/search` to find the restaurant and get the venue_id. Don't guess venue IDs. 3. **Link Resy before booking** — the user must have a linked Resy account with a payment method on file in Resy. 4. **Always fetch fresh availability** — the `config_id` changes each time. Never reuse a config_id from a previous availability check. 5. **Use the date format YYYY-MM-DD** — e.g. `2026-04-15`, not `April 15th`. 6. **Confirm before booking** — always show the user what you're about to book (restaurant, date, time, party size) and get their confirmation before calling `POST /api/book`. 7. **Follow next_step on errors** — every error response includes a `next_step` field telling you exactly how to recover. ## Quick Reference | Endpoint | Method | Auth | Cost | Purpose | |----------|--------|------|------|---------| | /api/me | GET | Wallet | Free | Check profile + Resy status (call first) | | /api/search | GET | None | Free | Search Resy for restaurants | | /api/account | POST | Wallet | Free | Create account + link wallet | | /api/link-resy | POST | Wallet | Free | Link Resy account (2-step OTP) | | /api/availability | GET | Wallet | Free | Check available time slots | | /api/book | POST | Wallet | 0.10 USDC | Book a reservation | [Full API Reference](https://www.agentres.dev/api-reference.md) — detailed request/response schemas, auth details, and error codes.