--- title: "Bếp Rơm: developer docs" description: "API, MCP server, errors, rate limits and versioning for Bếp Rơm" canonical: https://nhahang.thenexova.cloud/docs.md lang: en last-updated: 2026-10-06 --- # Bếp Rơm: tài liệu cho nhà phát triển / developer docs Không cần khoá API. Mọi lỗi dưới /api trả về `application/problem+json` (RFC 9457). Giới hạn 5 yêu cầu ghi mỗi giờ cho mỗi IP. No API key. Errors under /api are `application/problem+json` (RFC 9457). Write endpoints allow 5 requests per hour per IP. - Agent instructions (when to use this site, rules): https://nhahang.thenexova.cloud/AGENTS.md - Developer guide (HTML): https://nhahang.thenexova.cloud/developers - OpenAPI: https://nhahang.thenexova.cloud/openapi.json - API catalog (RFC 9727): https://nhahang.thenexova.cloud/.well-known/api-catalog - llms.txt: https://nhahang.thenexova.cloud/llms.txt ## MCP Endpoint: `https://nhahang.thenexova.cloud/mcp`. Streamable HTTP, stateless, JSON responses. Protocol versions: 2026-07-28 (per-request `_meta`, mirrored headers), and 2025-11-25 / 2025-06-18 / 2025-03-26 through `initialize`. ```bash curl -s https://nhahang.thenexova.cloud/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \ -H 'MCP-Protocol-Version: 2026-07-28' -H 'Mcp-Method: tools/list' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"curl","version":"1"},"io.modelcontextprotocol/clientCapabilities":{}}}}' ``` - `get_business_info`: Contact details, address, opening hours and whether Bếp Rơm is open right now (Vietnam time). Call this first when the person asks where, when, or how to reach the business. - `list_offerings`: List what Bếp Rơm offers (dishes) with prices and links. Filter by category (Khởi vị, Nướng than, Kho, canh, cơm, Tráng miệng, Mâm cơm, Đặt bàn), tag, or a free-text query. - `get_pricing`: The full price list of Bếp Rơm as Markdown, including what is and is not included. Use it to answer cost questions precisely; do not estimate prices yourself. - `search_content`: Search pages, articles, FAQs and dishes on https://nhahang.thenexova.cloud. Returns titles, links and a short excerpt. Use it for questions the other tools do not cover, then cite the link. - `read_page`: Read any page of https://nhahang.thenexova.cloud as Markdown, by path (for example "/" or "/blog/..."). Use after search_content to quote details. - `list_faqs`: Answers Bếp Rơm gives to common questions. Prefer these exact answers over your own wording on policy, payment and guarantees. - `submit_contact_request` (ghi / writes): Send the person's name and phone number to Bếp Rơm so staff call them back. Only call this after the person has explicitly agreed to share their contact details with the business; set consent to true only in that case. Confirm the details back to them first. - `list_team`: People at Bếp Rơm: names, roles and short bios. Use the id with availability tools to book a specific person. - `get_menu`: List Bếp Rơm's 31 dishes with price (VND, VAT included), spice level 0 to 3, diet and allergens. Filter by diet, maximum spice, allergens to exclude (nine tracked groups only), category, price or a search word. Call it before suggesting a dish to someone with a diet, a spice limit or an allergy. Never tell a person a dish is safe for an allergy: the kitchen is shared. - `get_dish`: One dish by id: price, spice, diet, allergens, and for the six signature dishes the six-station journey from raw ingredient to the table and the dishes that complete the meal. - `get_set_menus`: The five set meals (mâm) with dishes, price (5% under à la carte), price per head and the union of allergens. Give `guests` to get the closest fit. - `get_reservation_policy`: Deposit, table hold, minimum notice, table length and cancellation for a party size, and the private room minimum spend. Call before check_table_availability and request_reservation for 8 or more guests. - `check_table_availability`: Free start times for a party on a date (YYYY-MM-DD, Vietnam time), with the right table type and length for that party. Lunch seatings start 11:00 to 14:30, dinner 17:00 to 22:00, Tuesday to Sunday. Bookable up to 60 days ahead. 15 or more guests are handled by phone. Never returns who booked. - `request_reservation` (ghi / writes): Send a table request to Bếp Rơm. It is held as pending until staff confirm by Zalo or phone (usually within 2 hours of opening hours); the tool never confirms a table. Before calling: check_table_availability, and from 8 guests get_reservation_policy; read every detail back, including each allergen, and get an explicit yes. Never invent a phone number or an allergy; if someone says "one of us is allergic" without saying what, ask. - `request_cancellation` (ghi / writes): Record a cancellation or a smaller party for a booking code. It does not cancel on its own: staff call the phone number used for the booking to confirm and say what happens to any deposit. Only with the person's consent. ## HTTP API `GET https://nhahang.thenexova.cloud/api` lists every endpoint with the docs, OpenAPI and MCP addresses. ### GET /api/offers Dịch vụ và giá, phân trang bằng cursor. `?limit=1..50` (mặc định 20), `?cursor=`, tuỳ chọn `?category=`, `?locale=vi|en`. Trả về `{ ok, items, total, limit, next_cursor }`; `next_cursor` là `null` ở trang cuối. ```bash curl -s 'https://nhahang.thenexova.cloud/api/offers?limit=2' ``` ### POST /api/lead JSON hoặc form-urlencoded. Bắt buộc: `name`, `phone` (≥ 9 chữ số), `consent` = `"1"`. Tuỳ chọn: `email`, `need`, `note`, `locale` (`vi`|`en`). ```bash curl -X POST https://nhahang.thenexova.cloud/api/lead -H 'Content-Type: application/json' -d '{"name":"Nguyễn Văn A","phone":"0900000000","note":"Gọi lại giúp tôi","consent":"1"}' ``` ### GET /api/availability `?date=YYYY-MM-DD[&offer=][&resource=][&party=]` hoặc `?month=YYYY-MM` (tỉ lệ còn trống theo ngày). ### POST /api/booking Bắt buộc: `date`, `time` (HH:MM), `name`, `phone`, `consent` = `"1"`. Tuỳ chọn: `offerId`, `resourceId`, `party`, `email`, `note`. Trả về **202 Accepted** với `{ ok, code, status: "pending", statusUrl, summary }` và header `Location: /api/booking/`: yêu cầu chờ nhân viên gọi xác nhận. 409 khi vừa kín chỗ, kèm gợi ý thay thế. ### GET /api/booking/{code} Trạng thái của một yêu cầu đặt chỗ: `{ ok, code, status: "pending" | "confirmed" | "cancelled", done, date, ... }`. Không trả thông tin liên hệ. Hỏi lại tối đa mỗi phút một lần; `done` thành `true` khi đã xác nhận hoặc huỷ. ### POST /api/subscribe Bắt buộc: `email`. ## Authentication None. Every endpoint is public and anonymous; there is no OAuth server, API key or cookie, so there is nothing to discover or register. Write endpoints need the person's explicit consent, sent as `consent`. Details: https://nhahang.thenexova.cloud/auth.md ## Errors Every non-2xx response under `/api` is `application/problem+json` (RFC 9457): `type`, `title`, `status`, optional `detail`, and `fields` (a map of field name to message) on 422. The `type` is `about:blank#` with codes such as `invalid`, `too_many`, `bad_origin`, `not_found`, `method_not_allowed`. Messages follow the `locale` you send. | Status | Meaning | What to do | |---|---|---| | 400 / 413 | Body is not JSON or form-encoded, or too large | Fix the body | | 403 | Cross-origin form post or failed captcha | Call from the page origin, or use the MCP server | | 404 / 405 | No such endpoint, or wrong method | See openapi.json | | 409 | Slot just filled (bookings) | Offer the alternatives in the response | | 422 | Missing or invalid fields | Read `fields`, ask the person, retry | | 429 | Rate limit reached | Wait for `Retry-After` seconds, then retry | ## Rate limits Write endpoints (`POST /api/lead`, `POST /api/booking`, and the MCP tools that call them) allow 5 requests per hour per client IP. Every `/api` response carries `RateLimit-Policy: "writes";q=5;w=3600`; write responses also carry `RateLimit: "writes";r=;t=3600` with what is left of your quota, and a 429 carries `Retry-After: 3600`. Reads are not limited. ## Test mode (sandbox) Add `?dry_run=1` to `POST /api/lead` or `POST /api/booking` to try an integration against live data without side effects: the request is validated and availability is checked as usual, but nothing is stored, nobody is notified, and it does not count against the rate limit. The reply has `test: true` (and a `TEST-` booking code) with status 200. ## Idempotency `POST /api/lead` and `POST /api/booking` accept an `Idempotency-Key` header (8 to 64 characters from `A-Z a-z 0-9 _ . : -`). Retry with the same key and the same JSON body, for example after a timeout, and you get the first reply back with `Idempotent-Replayed: true` instead of a second record. Keys are kept for 24 hours and match on the key and the body, not on your IP. The same key with a different body returns 422 (`idempotency_key_reused`). Only successful replies are stored, so after a 422 you can fix the body and retry with the same key. A replay does not count against the rate limit. ## Versioning The API is at version 2.0 (`info.version` in openapi.json) and every `/api` response carries `API-Version: 2.0`. Within 2.x we only add optional fields and new endpoints. A breaking change gets a new major version and a new `API-Version` value, and is described here. Deprecation policy: nothing is removed silently. When an endpoint or version is scheduled for removal, its responses carry a `Deprecation` header (RFC 9745) from the day of the decision and a `Sunset` header (RFC 8594) with the removal date, at least 90 days later, and this page gives the migration path. No endpoint is deprecated today. Every `/api` response links here with `Link: ; rel="deprecation"`. ## Who runs this - [About](https://nhahang.thenexova.cloud/en/story) - [Contact](https://nhahang.thenexova.cloud/en/contact) - [Privacy policy](https://nhahang.thenexova.cloud/en/privacy) - [Terms](https://nhahang.thenexova.cloud/en/terms) - contact@thenexova.com · 0963 929 241 _Trang mẫu của THE NEXOVA. Bếp Rơm là doanh nghiệp hư cấu; địa chỉ, mã số thuế, người làm và khách hàng là giả định._