canonical: https://jentic.com/apis/heyyumi.ai/heyyumi # HeyYumi API The HeyYumi API serves refined food and drink venue data so an agent can find, recommend, and book places: each venue carries identity, location, standardized hours, menu, price band, rating, and freshness and confidence signals. You search and run nearby lookups, read a venue's full detail and history, resolve regions and categories, and request reservations. A field mask on the fields query param lets you choose which data tiers you receive, and a live-status endpoint asks a venue its current state on demand. ## For AI agents Search refined food and drink venue data by category, region, and price band, read standardized hours and ratings, check a venue's live status, and request a reservation. A curated dining dataset served as a REST API. ## Scope Does not deliver food, process payments, or cover venues outside its curated food and drink dataset. Use for discovering, detailing, and booking food and drink venues only. ## Capabilities - Search food and drink venues and filter by category, region, price band, rating, and freshness - Run a nearby search to find venues around a point - Retrieve a venue's full detail, including standardized hours and menu, using a field mask on the fields param - Request a reservation at a venue and poll its status - Ask a venue for its live status right now and read the result - Resolve region and dong names and list categories and dataset stats ## Use cases ### Agent Venue Discovery and Booking An AI concierge agent uses the HeyYumi API through Jentic to find, recommend, and book food and drink venues: it searches places by category, region, and price band, reads a venue's standardized hours, menu, and rating, and requests a reservation, then polls the reservation status. A field mask on the fields query param lets the agent pull only the tiers it needs, keeping responses lean. Because a reservation is a single POST and status is a long-poll GET, the agent can complete a booking end to end. Example prompt: Search venues in a region filtered by price band, read the top result's hours and menu, then request a reservation and poll its status ### Nearby Food & Drink Search A local-discovery app finds venues around a point using the HeyYumi nearby search, returning identity, location, standardized hours, rating, and freshness for each. The fields query param selects which tiers come back, and the regions and categories endpoints help turn a neighborhood name or cuisine into a filter. This powers a 'what is good near me' experience on refined venue data. Example prompt: Run a nearby search around a coordinate, filter to open venues, and return each venue's name, rating, and hours ### Live Venue Status Checks Before recommending a venue, an application confirms its current state with the HeyYumi live-status endpoint, which asks the venue right now and returns the answer on a long-poll. Paired with the standardized hours and the freshness and confidence signals on each place, this reduces the chance of sending a user to a closed or stale listing. The result is retrieved by its queryId once ready. Example prompt: Submit a live-status query for a venue, then poll the result by queryId and report whether it is open ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/api/v1/places` | Search food and drink venues | | GET | `/api/v1/places/nearby` | Nearby venue search | | GET | `/api/v1/places/{id}` | Venue detail | | GET | `/api/v1/places/{id}/history` | Venue history | | POST | `/api/v1/reservations` | Request a reservation | | GET | `/api/v1/reservations/{id}` | Reservation status (long-poll) | | POST | `/api/v1/live-status` | Ask the venue its live status now | | GET | `/api/v1/regions` | Resolve a region or dong name | ## Key resources - **Places** — Search, nearby search, detail, and history for food and drink venues with a field mask - **Reservations** — Request a reservation and poll its status - **Live status** — Ask a venue its current status and read the long-poll result by queryId - **Reference** — Regions and dong-name resolution, categories, dataset stats, and filter and field vocabulary ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 65 / 100 - **Maturity:** AI-Aware - **Dimensions:** - Foundational Compliance: 76 / 100 - Developer Experience & Jentic Compatibility: 66 / 100 - AI-Readiness & Agent Experience: 49 / 100 - Agent Usability: 94 / 100 - Security: 55 / 100 - AI Discoverability: 76 / 100 - **View full report:** https://jentic.com/apis/heyyumi.ai/heyyumi/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring the HeyYumi API by hand means handling its bearer token or `X-API-Key` header, learning the field-mask tiers on the fields query param, and polling reservation and live-status results yourself. Through Jentic you install once, import it from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** HeyYumi puts the place and reservation ids in the URL path, so a rule can bound your agent to specific read operations while leaving writes out. You choose the operations it may call, so a read-only agent can search venues and read details without being able to request a reservation unless you add that operation. - **Credential handling:** Your HeyYumi API key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'find a restaurant nearby' or 'book a table', and Jentic returns the matching HeyYumi operation with its input schema so the agent sets the right filters without reading the reference docs. ## Related APIs - **Yelp** — A broad business and review dataset with venue search, versus HeyYumi's curated food and drink data plus reservations. - **Foursquare** — A places and points-of-interest search API across all categories, versus HeyYumi's food and drink focus. - **OpenTable** — A dedicated restaurant reservation network that can fulfil bookings for venues you discover. ## FAQ ### What authentication does the HeyYumi API use? The HeyYumi API accepts a bearer token in the Authorization header or an API key in the `X-API-Key` header, per its OpenAPI spec; passing the key in the query string is deprecated. Through Jentic the key is stored encrypted by your own Jentic One instance and injected at call time, so it never appears in a URL or the agent's logs. ### Can I search and book venues with the HeyYumi API? Yes. You search places, run a nearby search, and read a venue's detail, hours, menu, and rating, using the fields query param to choose which tiers you receive. You then request a reservation with a single POST and poll its status, and you can ask a venue for its live status right now. ### What are the rate limits for the HeyYumi API? The OpenAPI spec does not specify request rate limits; billing is tiered by the fields you request through the field mask. For current limits and tier details, see the HeyYumi documentation at https://heyyumi.ai. ### How do I book a venue through Jentic? Search Jentic with a query like 'book a table', add the HeyYumi API from the directory, and store your API key once. Your agent searches for a venue, requests a reservation with a POST, and polls the reservation status until it resolves. To run it on your own infrastructure, install Jentic One from its GitHub repo. ### Can I limit what my agent is allowed to do with the HeyYumi API? Yes. Write a rule that allows only the read operations, such as searching places and reading venue details, so the agent can discover and recommend venues but cannot request a reservation unless you add that operation, with every call logged. Place and reservation ids travel in the URL path, so scoping bounds which operations run. ### Is there a HeyYumi API MCP server? You don't need an MCP server to give your agent the HeyYumi API. Jentic connects it directly from the API Directory: import it, store your API key once, and your agent calls the search, detail, and reservation operations on demand without loading another server's tool definitions into its context.