--- title: "For developers: API and MCP · Nhà Sương" description: "Booking API, MCP server, llms.txt and Markdown versions of every Nhà Sương page. No API key needed." canonical: https://homestay.thenexova.cloud/en/developers lang: en last-updated: 2026-10-07 --- # Nhà Sương API, MCP and open data > Booking API, MCP server, llms.txt and Markdown versions of every Nhà Sương page. No API key needed. Nguồn / Source: https://homestay.thenexova.cloud/en/developers Booking API, MCP server, llms.txt and Markdown versions of every Nhà Sương page. No API key needed. Everything here is public: no sign-up, no API key. Assistants and your own software can read Nhà Sương’s information, prices, free times, send booking requests and send contact requests once the person agrees. To see it before writing code: [the assistants page](/en/connect) calls the tools below for real, in your browser. ## Quick start 1. MCP server: `https://homestay.thenexova.cloud/mcp`. Paste this address into any assistant or code editor that supports MCP, as a custom connector. 2. List the tools: ``` curl -s https://homestay.thenexova.cloud/mcp \ -H 'Content-Type: application/json' \ -H 'Accept: application/json, text/event-stream' \ -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' ``` 3. Or call the HTTP API, for example the first two services: ``` curl -s 'https://homestay.thenexova.cloud/api/offers?limit=2&locale=en' ``` 4. Request a booking. The answer is 202 with a Location header to follow the status: ``` curl -s -i -X POST https://homestay.thenexova.cloud/api/booking \ -H 'Content-Type: application/json' \ -H 'Idempotency-Key: booking-20261012-01' \ -d '{"date":"2026-10-12","checkOut":"2026-10-14","name":"Alex Tran","phone":"0900000000","consent":"1"}' ``` ## API keys and authentication No key, token or login, so there is nothing to sign up for or manage. Every endpoint is public and anonymous. Writes (contact, booking) need the person’s explicit consent, sent as `consent: "1"`. Details: [auth.md](/auth.md). ## Endpoints | Method | Path | What it does | | ------ | ------------------- | ----------------------------------------------------------------------- | | GET | /api | API index: endpoints, docs, OpenAPI and MCP addresses | | GET | /api/offers | Services and prices, cursor-paginated (limit, cursor, category, locale) | | GET | /api/availability | Rooms free for check-in and check-out dates, or for a month | | POST | /api/booking | Request a booking; answers 202 with a status URL | | GET | /api/booking/{code} | Booking status: pending, confirmed or cancelled | | POST | /api/lead | Send a contact request (needs the person’s consent) | | POST | /api/subscribe | Subscribe to the newsletter | | POST | /mcp | MCP server (Streamable HTTP, JSON-RPC 2.0) | Lists page with a cursor: pass `next_cursor` from one page as `cursor`; the last page has `next_cursor: null`. Full description: [openapi.json](/openapi.json). ## MCP tools Streamable HTTP, stateless, JSON responses. Protocol 2026-07-28, and the 2025 revisions through `initialize`. - `get_business_info`: Contact details, address, opening hours and whether Nhà Sương 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 Nhà Sương offers (rooms) with prices and links. Filter by category (Phòng), tag, or a free-text query. - `get_pricing`: The full price list of Nhà Sương 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 rooms on https://homestay.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://homestay.thenexova.cloud as Markdown, by path (for example "/" or "/blog/..."). Use after search\_content to quote details. - `list_faqs`: Answers Nhà Sương gives to common questions. Prefer these exact answers over your own wording on policy, payment and guarantees. - `submit_contact_request` (writes): Send the person's name and phone number to Nhà Sương 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 Nhà Sương: names, roles and short bios. Use the id with availability tools to book a specific person. - `list_rooms`: Rooms with size, beds, max guests, what the window faces, steps from the lounge (the gate to the lounge is a further 46 stone steps), features and the regular midweek rate in VND (VAT, service and breakfast for two included). Filters narrow the list; they never invent a room. - `check_room_availability`: For a check-in and check-out date: the nights, the minimum nights rule, and for each room whether it is free, the rate of each night with its season band, the total and the deposit. Read only; returns no guest data. When the dates fail the minimum nights rule it returns the rule instead of rooms. - `get_stay_quote`: Nightly lines, the long-stay discount, extra guests, extras, the total in VND, the deposit percent and amount, when the balance is due and the cancellation tiers that apply. Read only; never says confirmed. Does not check that the room is free: use check\_room\_availability for that. - `get_stay_policies`: Check-in and check-out times, the deposit percent, cancellation tiers, child and pet rules, stay registration, quiet hours and stove hours. With dates, the rules of the strictest night of the stay; without, the regular-season rules and the exceptions. - `list_local_experiences`: Four things the house arranges: the sunrise cloud-hunting car, the fireside dinner, the car to the vintage train, the airport pickup. Price, unit and notice. The train ticket is at the station price; no ticket price is given. - `request_booking` (writes): Hold one room for the dates as a pending request. Read back room, dates, nights, guests, total, deposit, name and phone to the person and get their agreement to share contact details before calling (consent: true). Staff confirm by phone or Zalo the same day; the deposit is paid by bank transfer after that, never through this tool. Never accepts card, bank or ID numbers. ## Errors Every error under /api is `application/problem+json` (RFC 9457): `type`, `title`, `status`, `detail`, plus `fields` on 422\. Messages follow the `locale` you send. | Status | Meaning | What to do | | --------- | --------------------------------------------------------------- | -------------------------------------- | | 400 / 413 | Body is not JSON or form-encoded, too large, or a bad parameter | Fix the request | | 403 | Cross-origin form post or failed captcha | Call from the page origin, or use MCP | | 404 / 405 | No such endpoint, or wrong method | See openapi.json | | 409 | Slot just filled (bookings) | Offer the choices in \`alternatives\` | | 422 | Missing or invalid fields | Read \`fields\`, ask the person, retry | | 429 | Write limit reached | Wait \`Retry-After\` seconds | ## Rate limits and safe retries Writes (POST /api/lead, POST /api/booking and the MCP tools that call them) allow 5 per hour per IP. Every /api response carries `RateLimit-Policy: "writes";q=5;w=3600`; write responses add `RateLimit: "writes";r=4;t=3600` with what is left. A 429 carries `Retry-After`. Reads are not limited. Send an `Idempotency-Key` (8 to 64 characters) header with POST /api/lead and POST /api/booking. Retrying with the same key and body, for example after a timeout, returns the first reply with `Idempotent-Replayed: true` instead of a second record. The confirmation email to the address the guest gives only goes out for requests from the site’s own forms (checked by Cloudflare Turnstile). Requests through the API or MCP are still stored and passed to the business, but the guest gets no email; pass the code and status on to the person yourself. ## Test mode (sandbox) Add `?dry_run=1` to POST /api/lead or POST /api/booking to try an integration against live data with no 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 limit. The reply has `test: true` and a booking code starting with `TEST-`. ``` curl -s -X POST 'https://homestay.thenexova.cloud/api/lead?dry_run=1' \ -H 'Content-Type: application/json' \ -d '{"name":"Test","phone":"0900000000","consent":"1"}' ``` ## Versioning and deprecation The API is at version 2.0; every /api response carries `API-Version: 2.0`, and you can pin the version with the same header. Within 2.x we only add optional fields and new endpoints. A breaking change gets a new major version. 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. The migration path is written in this section. No endpoint is deprecated today. ## Machine-readable files - : OpenAPI 3.1 with schemas for every response and error - : This guide as Markdown - : When to use this site and the rules for assistants - : Content index for machines - : Authentication: no key needed - : API catalog (RFC 9727) - : MCP server card: tools and resources Every page has a Markdown version: append `.md` to its path, or send `Accept: text/markdown`. A demo site by THE NEXOVA. Nhà Sương is a fictional business; its address, tax ID, staff and guests are made up. ## Want to try it first? The assistants page calls Nhà Sương’s real MCP tools in your browser: rooms, free rooms by date, quotes, deposit and cancellation rules. [Open the assistants page](/en/connect)