Lụa Spa API, MCP and open data

Everything here is public: no sign-up, no API key. Assistants and your own software can read Lụa Spa’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. Prices from the API match the price list.

Quick start

1. MCP server: https://spa.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://spa.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://spa.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://spa.thenexova.cloud/api/booking \
     -H 'Content-Type: application/json' \
     -H 'Idempotency-Key: booking-20261012-01' \
     -d '{"date":"2026-10-12","time":"10:00","offerId":"facial-lam-diu","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 Lụa Spa 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 Lụa Spa offers (treatments) with prices and links. Filter by category (Chăm sóc da mặt, Massage body, Gội đầu dưỡng sinh, Gói kết hợp), tag, or a free-text query.
• get_pricing: The full price list of Lụa Spa 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 treatments on https://spa.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://spa.thenexova.cloud as Markdown, by path (for example "/" or "/blog/..."). Use after search_content to quote details.
• list_faqs: Answers Lụa Spa 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 Lụa Spa 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_services: Treatments with minutes in the room, price in VND (VAT 8% included, no tip), which therapists do each, feeling tags and what is or is not in it. Category `the` lists memberships, `qua` gift cards.
• list_therapists: The four therapists: role, gender, working days (ISO weekdays) and which treatments each does. No photos of faces, no medical titles.
• suggest_treatment: The treatment finder as a tool: one treatment and one alternative from how the skin and body feel, the time available and any health boxes. Never a diagnosis. When a skin condition under treatment or a wound is set, no facial is suggested and needs_doctor_first is true.
• check_slots: Free start times for one treatment on one date (Vietnam time), optionally with one therapist or a therapist gender. Call this before request_appointment; say the end time and the price out loud; do not guess times. party_size 2 is only the For Two package in the double room.
• request_appointment (writes): Send a booking request; it stays pending until the front desk confirms by phone or Zalo. Before calling, confirm treatment, date, time, therapist, name and phone with the person, tell them "free change until 12 hours before", and get explicit agreement to share contact details and the health boxes. Do not promise any result of the treatment.
• request_change (writes): Ask the front desk to move or cancel a booking, given its code and the last four digits of the phone used. It never confirms by itself and never says who booked what; a wrong pair gets the same answer as a missing booking.
• list_gift_options: Gift card amounts, the option to name a treatment, validity, delivery and the company-order rule.
• request_gift_card (writes): Create a gift card order, pending payment by bank transfer (staff send the details after confirming). No money moves through this tool. The card is sent within one opening hour of the transfer.
• request_membership (writes): Create a membership card order (five or ten visits), pending payment by bank transfer after staff confirm. No money moves through this tool.

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://spa.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. Lụa Spa is a fictional business; its address, tax ID, therapists and clients are made up.