Nhà Sương API, MCP and open data

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 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.

Endpoints

Lists page with a cursor: pass next_cursor from one page as cursor; the last page has next_cursor: null. Full description: 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.

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.

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.json: OpenAPI 3.1 with schemas for every response and error
• /docs.md: This guide as Markdown
• /AGENTS.md: When to use this site and the rules for assistants
• /llms.txt: Content index for machines
• /auth.md: Authentication: no key needed
• /.well-known/api-catalog: API catalog (RFC 9727)
• /.well-known/mcp/server-card.json: 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.