--- name: agentres.dev description: agentres.dev provides a three-skill API for integrating Resy restaurant reservation workflows into agent pipelines. It handles AgentRes account initialization, Resy account linking via email OTP, and venue search by name, cuisine, or keyword. It does not currently expose reservation availability checks or booking endpoints directly. host: agentres.dev --- # agentres.dev agentres.dev is a middleware host that bridges agent authentication and Resy's restaurant reservation platform. It serves agents that need to programmatically set up user accounts, authenticate against Resy, and discover venue IDs before handing off to reservation or booking flows. Its scope is limited to account setup, account linking, and venue discovery — it is not a full reservation management API. ## When to use this host Use agentres.dev when an agent needs to initialize an AgentRes account, link a Resy user account via OTP, or look up Resy venue IDs by name or cuisine. This host is the correct starting point for any Resy-integrated reservation pipeline. Do not use it for checking table availability, making reservations, or canceling bookings — those operations are not exposed here and must be handled by a separate reservation endpoint or the Resy API directly. If the user's Resy account is already linked and the agent only needs venue search, skip setup-account and link-resy-account and call search-resy-venues directly. This host does not support cities outside its defined enum, so agents should map user location input to the closest supported city slug before calling search-resy-venues. ## Capabilities ### Account Initialization Establishes the AgentRes account identity for a caller, either via API key or wallet address, returning the user_id and wallet link status needed for downstream calls. - **`setup-account`** — Idempotently creates or retrieves the AgentRes account associated with the calling API key or wallet address, returning the account's user_id, email, and wallet link status. ### Resy Account Linking Connects a user's existing Resy account to the AgentRes workflow using a two-step email OTP flow, enabling reservation-related operations that require Resy authentication. - **`link-resy-account`** — Links a Resy account to an agent booking workflow via a two-step email OTP flow: first call sends the code, second call with the code completes linking. ### Venue Discovery Searches the Resy venue database by name, cuisine, or keyword within a supported city, returning venue IDs and metadata needed to proceed with availability lookups or bookings. - **`search-resy-venues`** — Searches the Resy venue database by name, cuisine, or keyword in a given city and returns the top 5 geo-ranked matches with venue IDs, neighborhoods, cuisines, and ratings. ## Workflows ### New User Onboarding and Venue Search *Use when an agent needs to onboard a new user from scratch and then find a restaurant on Resy — covering account creation, Resy account linking, and venue discovery in sequence.* 1. **`setup-account`** — Create or retrieve the AgentRes account for the user, obtaining a user_id and confirming wallet link status. 2. **`link-resy-account`** — Send the OTP to the user's Resy email (first call without code), then complete linking by submitting the code the user provides (second call with code). 3. **`search-resy-venues`** — Search for the target restaurant by name, cuisine, or keyword in the user's city to retrieve the venue_id needed for downstream reservation steps. ## Skill reference ### `link-resy-account` **Resy Account Linker** — Links a Resy account to an agent booking workflow via a two-step email OTP flow: first call sends the code, second call with the code completes linking. *Use when:* Use when an agent needs to connect a user's Resy account before performing reservation lookups or bookings; call once without a code to send the OTP, then again with the code the user provides to complete linking. *Not for:* Do not use for making or canceling reservations — this endpoint only handles account linking. Do not use if the Resy account is already linked. **Inputs:** - `em_address` (string, required) — Resy account email address. Must be the same email used across the entire setup flow. Used in both step 1 (send OTP) and step 2 (verify OTP). - `code` (string) — 6-digit OTP code received in the user's Resy email. Omit on the first call (step 1) to trigger code delivery; include on the second call (step 2) to complete linking. **Returns:** Returns step='code_sent' and a message instructing the user to check their email; on step 2 with a valid code, returns step='linked' and resy_user_id. **Example:** `{"em_address": "user@example.com"}` --- ### `setup-account` **Account Setup (AgentRes)** — Idempotently creates or retrieves the AgentRes account associated with the calling API key or wallet address, returning the account's user_id, email, and wallet link status. *Use when:* Use when an agent needs to initialize or retrieve an AgentRes account before calling downstream endpoints like /api/me or /api/link-resy. Call this first after choosing an auth path (API-key or wallet). API-key callers may send an empty body; wallet callers must supply the user's Resy email. *Not for:* Do not use to fetch full account profile details after setup — use GET /api/me instead. Do not use to link a Resy reservation account; use /api/link-resy for that step. **Inputs:** - `email` (string) — Contact/Resy email for the account. Required for wallet auth so a new wallet-owned account can be created and linked. Optional for API-key auth; if present, must match the key-owned account. **Returns:** Returns a JSON object with user_id (UUID), email, created (false when account already existed), wallet_linked (true/false), and wallet_address of the linked wallet. **Example:** `{"email": "agent@example.com"}` --- ### `search-resy-venues` **AgentRes Resy Venue Search** — Searches the Resy venue database by name, cuisine, or keyword in a given city and returns the top 5 geo-ranked matches with venue IDs, neighborhoods, cuisines, and ratings. *Use when:* Use when an agent needs to find Resy venue IDs for a restaurant by name, cuisine type, or keyword — especially before booking a reservation or looking up availability. Extract the city from the user's request and map it to a supported city slug. *Not for:* Do not use for checking reservation availability or making bookings; use a reservation lookup or booking endpoint instead. Not suitable for cities outside the supported enum — pick the closest supported city rather than guessing. **Inputs:** - `query` (string, required) — Restaurant name, cuisine type, or keyword to search for. - `city` (string) — City slug for geo-ranked search. Must be one of the supported enum values (e.g. nyc, los-angeles, chicago). Defaults to nyc if omitted. **Returns:** Returns a results array of up to 5 venues each with venue_id, name, neighborhood, cuisine array, and rating, plus the city slug used for the search. **Example:** `GET https://agentres.dev/api/search?query=Carbone&city=nyc` ---